ElementsElement Properties & Methods

Search element settings (Beta)

element.searchSettings()

Retrieve the configurable settings for an element, such as alt text, image source, heading tag, and link target.

The response includes full metadata including current values, binding information, resolved values, and display labels.

This method is available on all element types that have at least one setting. Results can be filtered by value type or by setting key.

Beta

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

This method does not support component instances. To retrieve the properties of a component instance, use element.searchProps().

Syntax

1element.searchSettings(options?: SearchSettingsOptions): Promise<Record<string, ElementSetting>>

Related interfaces:

1interface SearchSettingsOptions {
2  /** Filter to settings that produce a specific value type (e.g., "string", "image") */
3  valueType?: BindableValueType;
4  /** Filter to a specific setting by key (e.g., "domId", "assetId") */
5  key?: string;
6}
7
8interface ElementSetting {
9  valueType: BindableValueType;
10  canBind: boolean;
11  value: SettingValue;
12  resolvedValue: ResolvedValue | null;
13  display: SettingDisplay;
14}
15
16type SettingValue =
17  | { sourceType: 'static'; value: unknown }
18  | { sourceType: 'prop'; propId: string; propName: string; propType: string }
19  | { sourceType: 'cms'; collectionId: string; collectionName: string; fieldId: string; fieldName: string }
20  | { sourceType: 'locale'; fieldKey: string; fieldName: string }
21  | { sourceType: 'localeItem'; fieldKey: string; fieldName: string }
22  | { sourceType: 'page'; fieldKey: string; fieldName: string }
23  | { sourceType: 'conditional' }
24  | { sourceType: 'legacy' };
25
26interface SettingDisplay {
27  label: string;
28  group: string | null;
29  trueLabel?: string;
30  falseLabel?: string;
31}

Parameters

options (optional)

An object with the following optional properties:

PropertyTypeDescription
valueTypeBindableValueTypeFilter results to settings that produce a specific value type, such as "string", "image", "link", or "boolean".
keystringFilter results to a specific setting by key, such as "domId", "altText", or "assetId".

Both filters can be used together. When no options are provided, all settings for the element are returned.

Returns

Promise<Record<string, ElementSetting>>

A Promise that resolves to an object mapping setting keys to ElementSetting objects. Returns an empty object when the element has no settings or no settings match the filter criteria.

Each ElementSetting object has the following fields:

FieldTypeDescription
valueTypeBindableValueTypeThe data type this setting holds, such as "string", "image", "link", or "boolean".
canBindbooleanWhether this setting can be bound to a data source such as a prop, CMS field, or page field.
valueSettingValueThe current value. Always a { sourceType, ... } shape, as in the table below.
resolvedValueResolvedValue | nullThe final resolved value or null if the value is unset or unresolvable.
displaySettingDisplayDisplay metadata for rendering in UI. Includes label, group, and optional trueLabel and falseLabel for boolean settings.

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

sourceTypeDescriptionAdditional fields
"static"A directly set valuevalue
"prop"Bound to a component proppropId, propName, propType
"cms"Bound to a CMS collection fieldcollectionId, collectionName, fieldId, fieldName
"locale"Bound to a field on the current localefieldKey, fieldName
"localeItem"Bound to a field on a locale list itemfieldKey, fieldName
"page"Bound to a field on the current pagefieldKey, fieldName
"conditional"Unsupported conditional binding(none)
"legacy"Unsupported legacy binding(none)

Notes

  • textContent-type setting values are returned as { innerText: string } objects rather than bare strings.
  • When a setting is bound to a CMS source, resolvedValue is null. This is a current limitation.
  • Both Form and FormBlock elements return the same form settings (name, method, action, redirect, state). Selecting either element returns those settings for convenience.

Example

1// Get the selected element
2const element = await webflow.getSelectedElement();
3
4if (element) {
5  // Get all settings for the element
6  const allSettings = await element.searchSettings();
7  console.log(allSettings);
8  // Example result for an Image element:
9  // {
10  //   altText: {
11  //     valueType: 'altText',
12  //     canBind: true,
13  //     value: { sourceType: 'static', value: 'A sunset photo' },
14  //     resolvedValue: 'A sunset photo',
15  //     display: { label: 'Alt Text', group: null }
16  //   },
17  //   src: {
18  //     valueType: 'image',
19  //     canBind: true,
20  //     value: { sourceType: 'static', value: 'asset_abc123' },
21  //     resolvedValue: 'https://cdn.webflow.com/foo.jpg',
22  //     display: { label: 'Image', group: null }
23  //   },
24  //   domId: {
25  //     valueType: 'id',
26  //     canBind: true,
27  //     value: { sourceType: 'static', value: 'hero-img' },
28  //     resolvedValue: 'hero-img',
29  //     display: { label: 'ID', group: null }
30  //   }
31  // }
32
33  // Filter to only image-type settings
34  const imageSettings = await element.searchSettings({ valueType: 'image' });
35
36  // Get a specific setting by key
37  const altTextSetting = await element.searchSettings({ key: 'altText' });
38}

Designer ability

Checks for authorization only

Designer abilityLocaleBranchWorkflowSitemode
canAccessCanvasAnyAnyAnyAny