> This page is for Designer API.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.webflow.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.webflow.com/_mcp/server.

# Search props (Beta)

> Search the props on a component instance and return the information about matching props.

## `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

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

Related interfaces:

```typescript
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

```typescript
// 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      |