Search props (Beta) | Webflow Developer Documentation

`element.searchProps()`

Search the props on a component instance and return the information about matching props. Results are returned in the same order as the instance props panel on the canvas.

This method is the instance-level counterpart to getProps() on the component definition. While getProps() returns prop definitions, searchProps() returns prop values as they exist on a specific instance.

Beta

These methods are in public beta and may change with future releases.

Syntax

element.searchProps(options?: { valueType?: BindableValueType }): Promise<Array<InstanceProp>>

Related interfaces:

interface InstanceProp {
  /** The prop's ID (matches the ID from the component's getProps/createProp). */
  propId: string;
  /** The binding value type (e.g. "string", "boolean", "textContent"). */
  valueType: BindableValueType;
  /** Whether this instance has overridden the default value for this prop. */
  hasOverride: boolean;
  /** The current value — always a { sourceType, ... } shape. */
  value: SettingValue;
  /** The final resolved value (never a binding reference). null if unresolvable. */
  resolvedValue: ResolvedValue | null;
  /** The default value from the component definition. */
  defaultValue: ResolvedValue | null;
  /** Display metadata for rendering in UI. */
  display: SettingDisplay;
}
type SettingValue = StaticPropValue | BindingValue;
interface StaticPropValue {
  sourceType: 'static';
  value: ResolvedValue | null;
}
type BindingValue =
  | { sourceType: 'prop'; propId: string; propName: string; propGroup: string | null }
  | { sourceType: 'cms'; collectionId: string; collectionName: string; fieldId: string; fieldName: string; fieldGroup: string | null; fieldType: CmsFieldType }
  | { sourceType: 'locale'; fieldKey: string; fieldName: string; fieldType: 'string' }
  | { sourceType: 'localeItem'; fieldKey: string; fieldName: string; fieldType: 'string' }
  | { sourceType: 'page'; fieldKey: string; fieldName: string }
  | { sourceType: 'conditional' }
  | { sourceType: 'legacy' };
type ResolvedValue =
  | string
  | number
  | boolean
  | null
  | LinkResolvedValue
  | VideoResolvedValue
  | RichTextResolvedValue;
interface SettingDisplay {
  label: string;
  group: string | null;
  trueLabel?: string;
  falseLabel?: string;
}

Parameters

options (optional)

Property	Type	Description
`valueType`	`BindableValueType`	Filter results to props with an exact match on value type. Accepted values: `"text"`, `"boolean"`, `"imageAsset"`, `"link"`, `"video"`, `"richText"`, `"file"`, `"lottieAsset"`, `"riveAsset"`.

Returns

Promise<Array<InstanceProp>>

A Promise that resolves to an array of InstanceProp objects in panel display order.

Each InstanceProp has the following fields:

Field	Type	Description
`propId`	`string`	The prop’s ID. Matches the ID from the component definition’s `getProps()`.
`valueType`	`BindableValueType`	The binding value type of the prop.
`bindableTo`	`readonly BindableValueType[]`	The value types that this prop can bind to.
`hasOverride`	`boolean`	Whether this instance has overridden the component’s default value for this prop.
`value`	`StaticValue \| BindingValue`	The current value. Always a `{ sourceType, ... }` shape — see the table below.
`resolvedValue`	`unknown \| null`	The final resolved value. Never a binding reference. `null` if unresolvable.
`defaultValue`	`unknown \| null`	The default value from the component definition.
`display`	`InstancePropDisplay`	Display metadata for rendering in UI. Includes `label`, `group`, and optional `trueLabel` and `falseLabel` for boolean props.

The value field always uses a { sourceType, ... } shape. The possible variants are:

`sourceType`	Description	Additional fields
`"static"`	A directly set value	`value`
`"prop"`	Bound to a component prop	`propId`, `propName`
`"cms"`	Bound to a CMS collection field	`collectionId`, `collectionName`, `fieldId`, `fieldName`, `fieldType`
`"locale"`	Bound to a field on the current locale	`fieldKey`, `fieldName`
`"localeItem"`	Bound to a field on a locale list item	`fieldKey`, `fieldName`
`"page"`	Bound to a field on the current page	`fieldKey`, `fieldName`
`"conditional"`	Unsupported conditional binding	(none)
`"legacy"`	Unsupported legacy binding	(none)

Example

// Find a component instance on the page
const elements = await webflow.getAllElements();
const instanceEl = elements.find(el => el.type === 'ComponentInstance');
if (instanceEl?.type === 'ComponentInstance') {
  // Get all props on the instance
  const props = await instanceEl.searchProps();
  console.log(props);
  // [
  //   {
  //     propId: 'prop_1',
  //     valueType: 'textContent',
  //     bindableTo: ['string', 'textContent'],
  //     hasOverride: true,
  //     value: { sourceType: 'static', value: 'My Custom Title' },
  //     resolvedValue: 'My Custom Title',
  //     defaultValue: 'Welcome to our site',
  //     display: { label: 'Heading', group: 'Content' }
  //   },
  //   {
  //     propId: 'prop_3',
  //     valueType: 'textContent',
  //     bindableTo: ['string', 'textContent'],
  //     hasOverride: false,
  //     value: {
  //       sourceType: 'cms',
  //       collectionId: 'col_abc123',
  //       collectionName: 'Blog Posts',
  //       fieldId: 'field_author',
  //       fieldName: 'Author Name',
  //       fieldType: 'plainText'
  //     },
  //     resolvedValue: 'Jane Doe',
  //     defaultValue: '',
  //     display: { label: 'Author', group: 'Content' }
  //   },
  //   {
  //     propId: 'prop_4',
  //     valueType: 'boolean',
  //     bindableTo: ['boolean', 'string'],
  //     hasOverride: false,
  //     value: { sourceType: 'static', value: true },
  //     resolvedValue: true,
  //     defaultValue: true,
  //     display: { label: 'Show CTA', group: 'Settings', trueLabel: 'Visible', falseLabel: 'Hidden' }
  //   }
  // ]
  // Filter to only text props
  const textProps = await instanceEl.searchProps({ valueType: 'textContent' });
}

Error handling

Scenario	Error tag	Message
Element is not a component instance	`ResourceMissingWithData`	`"Element is not a component instance: <id>"`
Invalid `valueType` filter	`InvalidRequest`	`"Invalid valueType: <valueType>"`
Insufficient permissions	`Forbidden`	`"Insufficient permissions to access element"`

Designer ability

Checks for authorization only

Designer ability	Locale	Branch	Workflow	Sitemode
canAccessCanvas	Any	Any	Any	Any