> 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. # Collection List settings > Read, discover, and update Collection List settings with the Designer API. 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. ```typescript const element = await webflow.getSelectedElement(); if (!element || element.type !== "DynamoWrapper") { throw new Error("Select a Collection List element."); } ``` ## Methods | Method | Description | | :--------------------------------------- | :--------------------------------------------------------------------------------------- | | `element.getSettings()` | Returns the current Collection List settings. | | `element.searchSettings()` | Returns Collection List settings as structured, non-bindable settings. | | `element.setSettings(settings)` | Updates one or more Collection List settings. | | `element.searchAvailableSources()` | Lists collections and multi-reference fields this Collection List can use as its source. | | `element.searchAvailableFields()` | Lists fields available for filtering and sorting. | | `element.searchAvailableItems(options?)` | Searches CMS items for curated lists and reference field filters. | ## Settings | Setting | Description | | :--------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `source` | The connected CMS collection, as `{ collectionId }`. Pass `null` to disconnect the source. | | `queryMode` | `"dynamic"` or `"curated"`. Pass `null` to reset to `"dynamic"`. | | `filters` | The ordered list of filter rules. Pass `null` or `[]` to clear filters. | | `filterMatch` | `"all"` or `"any"`. Pass `null` to reset to `"all"`. | | `sort` | The ordered list of sort rules. Pass `null` or `[]` to clear sort. | | `limit` | The maximum number of items to show, from `1` to `100`. Pass `null` to reset to `100`. | | `offset` | The number of items to skip. Pass `null` to reset to `0`. | | `pagination` | Pagination settings, as `{ itemsPerPage }`. Pass `null` to disable pagination. `setSettings()` rounds `itemsPerPage` up and clamps it to `1` through `100`. | | `curatedItemIds` | The ordered list of selected CMS item IDs for curated mode. | `setSettings()` accepts partial updates. The method changes only the keys you include. ## Read settings Use `getSettings()` to get the raw Collection List settings. ```typescript const collectionList = await webflow.getSelectedElement(); if (collectionList?.type === "DynamoWrapper") { const settings = await collectionList.getSettings(); console.log(settings.source); console.log(settings.filters); console.log(settings.pagination); } ``` 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`. ```typescript const settings = await collectionList.searchSettings({ valueType: "collectionListSetting", }); console.log(settings.source); /* { valueType: "collectionListSetting", canBind: false, value: { collectionId: "collection_123" }, display: { label: "Source", group: "Collection List" } } */ ``` You can also filter by setting key. ```typescript const filters = await collectionList.searchSettings({ key: "filters" }); console.log(filters.filters); /* { valueType: "collectionListSetting", canBind: false, value: [], display: { label: "Filters", group: "Collection List" } } */ ``` ## Discover valid values Use discovery methods before writing Collection List settings. They return the valid values for the current site and selected Collection List. ```typescript const sources = await collectionList.searchAvailableSources(); 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. ```typescript const { items, total } = await collectionList.searchAvailableItems({ query: "summer", page: 0, pageSize: 10, }); 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. ```typescript await collectionList.setSettings({ queryMode: "dynamic" }); const fields = await collectionList.searchAvailableFields(); const filterField = fields.find( (field) => field.canFilter && field.fieldType === "plainText" && field.filterOperators.includes("equals") ); const sortField = fields.find((field) => field.canSort); if (filterField) { await collectionList.setSettings({ filters: [ { fieldSlug: filterField.slug, operator: "equals", value: "summer", }, ], filterMatch: "all", }); } if (sortField) { await collectionList.setSettings({ sort: [{ fieldSlug: sortField.slug, direction: "ascending" }], }); } await collectionList.setSettings({ limit: 24, offset: 0, pagination: { itemsPerPage: 12 }, }); ``` ## 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. ```typescript await collectionList.setSettings({ queryMode: "curated" }); const { items } = await collectionList.searchAvailableItems({ query: "featured", pageSize: 6, }); await collectionList.setSettings({ curatedItemIds: items.map((item) => item.id), }); ``` `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. ```typescript await collectionList.setSettings({ filters: [ { fieldSlug: "name", operator: "equals", value: "summer" }, { fieldSlug: "featured", operator: "isOn" }, ], }); ``` 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. ```typescript await collectionList.setSettings({ filters: [ { fieldSlug: "published-on", operator: "greaterThanOrEqual", value: { amount: 7, unit: "days", direction: "past" }, }, ], }); ``` 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. ```typescript await collectionList.setSettings({ filters: [ { fieldSlug: "name", operator: "equals", value: { sourceType: "prop", propId: "prop_123" }, }, ], }); ``` A binding input object has one of these shapes: ```typescript type BindingInput = | { sourceType: "prop"; propId: string } | { sourceType: "cms"; collectionId: string; fieldId: string } | { sourceType: "page"; fieldKey: string } | { sourceType: "locale"; fieldKey: string } | { sourceType: "localeItem"; fieldKey: string }; ``` Use [`searchBindableSources()`](/designer/reference/element-bindings/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.