Collection List settings

The API exposes Collection List elements as DynamoWrapperElement objects. The element type string is the public, stable value "DynamoWrapper".

Use the Collection List settings methods to read and update a list’s CMS source, query mode, filters, sort order, item limit, offset, pagination, and curated items. You can also discover valid sources, fields, operators, options, and CMS items before writing settings.

Supported element

These methods are available on Collection List elements. Check that the selected element has type === "DynamoWrapper" before calling them.

1
const element = await webflow.getSelectedElement();
2
3
if (!element || element.type !== "DynamoWrapper") {
4
  throw new Error("Select a Collection List element.");
5
}

Methods

Settings

setSettings() accepts partial updates. The method changes only the keys you include.

Read settings

Use getSettings() to get the raw Collection List settings.

1
const collectionList = await webflow.getSelectedElement();
2
3
if (collectionList?.type === "DynamoWrapper") {
4
  const settings = await collectionList.getSettings();
5
6
  console.log(settings.source);
7
  console.log(settings.filters);
8
  console.log(settings.pagination);
9
}

Use searchSettings() when you need display metadata for settings UI. Collection List entries use valueType: "collectionListSetting" and canBind: false. They don’t include resolvedValue. searchSettings() returns a record keyed by setting name: source, queryMode, filters, filterMatch, sort, limit, offset, pagination, and curatedItemIds. For a disconnected Collection List, the source entry still has value: null.

1
const settings = await collectionList.searchSettings({
2
  valueType: "collectionListSetting",
3
});
4
5
console.log(settings.source);
6
/*
7
{
8
  valueType: "collectionListSetting",
9
  canBind: false,
10
  value: { collectionId: "collection_123" },
11
  display: { label: "Source", group: "Collection List" }
12
}
13
*/

You can also filter by setting key.

1
const filters = await collectionList.searchSettings({ key: "filters" });
2
3
console.log(filters.filters);
4
/*
5
{
6
  valueType: "collectionListSetting",
7
  canBind: false,
8
  value: [],
9
  display: { label: "Filters", group: "Collection List" }
10
}
11
*/

Discover valid values

Use discovery methods before writing Collection List settings. They return the valid values for the current site and selected Collection List.

1
const sources = await collectionList.searchAvailableSources();
2
const fields = await collectionList.searchAvailableFields();

searchAvailableFields() returns each field’s slug, display name, field type, filtering support, sorting support, and supported filter operators. Option fields include an options array. Reference fields include referenceCollectionId.

Use searchAvailableItems() to find CMS items. Without fieldSlug, it searches the Collection List’s connected collection. With fieldSlug, it searches the referenced collection for that field. Only pass fieldSlug for reference fields. This method can only retrieve CMS items in the Designer. Outside the Designer, the Promise rejects with an invalid request error.

1
const { items, total } = await collectionList.searchAvailableItems({
2
  query: "summer",
3
  page: 0,
4
  pageSize: 10,
5
});
6
7
console.log(items, total);

page is zero-based and must be a non-negative integer. The default pageSize is 50. pageSize must be an integer from 1 to 100. If page is past the available results, searchAvailableItems() returns an empty items array and the same total count for the query. searchAvailableItems() uses page and pageSize to page through discovery results. Dynamic Collection Lists use the offset, limit, and pagination settings for rendering instead.

Update a dynamic list

Use dynamic mode for filters, sort, limit, offset, and pagination. This example assumes a Collection List with a direct CMS collection connection.

1
await collectionList.setSettings({ queryMode: "dynamic" });
2
3
const fields = await collectionList.searchAvailableFields();
4
const filterField = fields.find(
5
  (field) =>
6
    field.canFilter &&
7
    field.fieldType === "plainText" &&
8
    field.filterOperators.includes("equals")
9
);
10
const sortField = fields.find((field) => field.canSort);
11
12
if (filterField) {
13
  await collectionList.setSettings({
14
    filters: [
15
      {
16
        fieldSlug: filterField.slug,
17
        operator: "equals",
18
        value: "summer",
19
      },
20
    ],
21
    filterMatch: "all",
22
  });
23
}
24
25
if (sortField) {
26
  await collectionList.setSettings({
27
    sort: [{ fieldSlug: sortField.slug, direction: "ascending" }],
28
  });
29
}
30
31
await collectionList.setSettings({
32
  limit: 24,
33
  offset: 0,
34
  pagination: { itemsPerPage: 12 },
35
});

Update a curated list

Use curated mode when you want to choose an ordered list of CMS items. This example assumes a Collection List with a direct CMS collection connection.

1
await collectionList.setSettings({ queryMode: "curated" });
2
3
const { items } = await collectionList.searchAvailableItems({
4
  query: "featured",
5
  pageSize: 6,
6
});
7
8
await collectionList.setSettings({
9
  curatedItemIds: items.map((item) => item.id),
10
});

curatedItemIds is only supported in curated mode. Use it only on Collection Lists connected directly to a CMS collection. Use item IDs from searchAvailableItems(). setSettings() validates that curatedItemIds is an array of strings, but doesn’t validate that each ID resolves to an item. Webflow skips IDs that don’t resolve to CMS items when the list renders. Filters, sort, limit, offset, and pagination are only supported in dynamic mode.

Mode and source changes

Changing the query mode clears settings from the previous mode.

• Switching to "curated" clears existing filters, filterMatch, sort, limit, offset, and pagination. If the same valid setSettings() call includes curatedItemIds, Webflow applies those IDs after the mode change.
• Switching to "dynamic" clears the curated item list.
• Webflow rejects a setSettings() call that switches to curated mode and also includes dynamic-only settings, such as filters or pagination, before any settings change.

Changing source clears the current query settings and pagination because filters, sort, limits, offsets, pagination, and curated items depend on the connected source.

Filter values

Build filter rules from the field metadata returned by searchAvailableFields(). Use only operators included in the field’s filterOperators array.

1
await collectionList.setSettings({
2
  filters: [
3
    { fieldSlug: "name", operator: "equals", value: "summer" },
4
    { fieldSlug: "featured", operator: "isOn" },
5
  ],
6
});

For option fields, pass an option ID from searchAvailableFields().options. For reference fields, use contains or doesNotContain with an item ID from searchAvailableItems(). For number and commerce price fields, pass numeric values as strings. For date comparison filters, pass a date filter value.

1
await collectionList.setSettings({
2
  filters: [
3
    {
4
      fieldSlug: "published-on",
5
      operator: "greaterThanOrEqual",
6
      value: { amount: 7, unit: "days", direction: "past" },
7
    },
8
  ],
9
});

For date filter values, unit can be "days", "weeks", "months", or "years". direction can be "past" or "future". amount must be a non-negative safe integer. Use amount: 0 for today.

Some filter values support data source bindings. Use a binding input object for equals and doesNotEqual on plain text, email, and phone fields. For number and commerce price fields, bound values support equals, doesNotEqual, greaterThan, and lessThan. The isSet and isOn operators can also use a binding input object as their value. Use static IDs for option and reference filters.

1
await collectionList.setSettings({
2
  filters: [
3
    {
4
      fieldSlug: "name",
5
      operator: "equals",
6
      value: { sourceType: "prop", propId: "prop_123" },
7
    },
8
  ],
9
});

A binding input object has one of these shapes:

1
type BindingInput =
2
  | { sourceType: "prop"; propId: string }
3
  | { sourceType: "cms"; collectionId: string; fieldId: string }
4
  | { sourceType: "page"; fieldKey: string }
5
  | { sourceType: "locale"; fieldKey: string }
6
  | { sourceType: "localeItem"; fieldKey: string };

Use searchBindableSources() to find valid binding inputs. For sourceType: "prop", propId is the ID of a component prop available to the current element.

Validation

setSettings() validates the whole update before changing the Collection List. If any setting is invalid, setSettings() leaves the list unchanged.

• Use searchAvailableSources() before setting source.
• Use searchAvailableFields() before setting filters or sort.
• limit must be an integer from 1 to 100.
• offset must be a non-negative safe integer. If the offset is beyond the available items, the Collection List has no items to render for that query.
• Pagination is only supported for dynamic Collection Lists connected directly to a CMS collection.
• curatedItemIds is only supported for curated Collection Lists connected directly to a CMS collection.
• pagination.itemsPerPage must be a finite number. setSettings() rounds it up, then clamps it to 1 through 100. For example, 12.2 becomes 13, 0 becomes 1, and 101 becomes 100.
• Changing source can fail when the Collection List item template contains bindings or nested lists.