Collection Lists

A Collection list is the element that repeats a design once for every item of a Collection. The designer builds one Collection item (a card, a table row, a list entry) and binds its child elements to fields; Webflow renders that item as many times as the list asks for, filling each copy with the data of one CMS item. It is the only way to show a variable number of CMS items on a page, and it is the most-used CMS element: the home page, the catalogue, the blog index, the footer’s recent-posts block and the related-items block of every template page are all Collection lists.

Three ideas are worth fixing before the details.

The concept is the counterpart of a query in other systems. In WordPress it is a WP_Query loop in a template or a Query Loop block, and in a framework such as Next.js it is a data fetch followed by a map. The difference in Webflow is that the query is configured in a panel, evaluated by the platform, and limited by it.

When you add a Collection list from the Add panel and choose a Collection, the Designer inserts a small tree of elements. Knowing the tree explains most layout surprises.

The list element has no visible box of its own beyond what you style. The most common first mistake is to style the Collection item as the layout container: the layout belongs on the list, and the item is the grid or flex child. This is the same rule as for any flex or grid container, covered in Flexbox and Grid Layouts.

A list has one of two modes. The choice decides which other settings exist.

Dynamic lists are the default. The list shows the items of the Collection that match its filters, in its sort order, up to its limit. When an editor adds a plant, the new plant appears on every dynamic list whose filter it matches after the next publish, without anyone touching the page. Filters, sort order, limit, offset and pagination are available only in this mode.

Curated lists show a hand-picked, ordered set of items. The designer chooses the items one by one in the list’s settings and orders them by dragging. A curated list is the right tool for a "Staff picks" or a homepage hero with three specific plants. Its drawback is that it is static: a new item never joins it, and an item that is later archived or deleted drops out. Curated lists have none of the filter, sort, limit, offset or pagination settings, and a curated list cannot be paginated.

The Designer API makes the split explicit: the queryMode setting is "dynamic" or "curated", switching to curated clears the dynamic-only settings, and combining curated mode with filters or pagination in one call is rejected. If a design needs "these five plants, plus whatever is newest", use a dynamic list with a filter on a featured switch field rather than a curated list, because the filter keeps working as content changes.

Binding connects the design to data. The steps in the Designer are the same for any list.

Binding is per element, not per list: two headings in the same card can be bound to two different fields. A field can be bound to text, to an image, to a link, to the visibility of an element (see Conditional Visibility and Dynamic Embeds), to a background image and to custom attribute values, and an item can link to its own template page through the Link to option of a link block set to the item’s page.

Select the Collection list and open Element settings, then Collection list settings. The panel contains the Collection, the filter block, the sort block, the limit, the offset and the pagination toggle. The Designer API names the same settings source, filters, filterMatch, sort, limit, offset and pagination.

A nested list is a Collection list inside the Collection item of another list. It is how a page shows one-to-many data: the zones of the garden, each with its plants, or each event with its guides. A nested list is the element that makes a multi-reference field visible, and it can also list items from another Collection that points back to the parent.

Setting one up for Fernbrook’s zones page:

Each nested list has its own filter, sort and limit settings, so a zone can show its three featured plants in alphabetical order. A nested list has no pagination of its own.

Source: Webflow Help Center: Collection list

When the query matches nothing, the list is replaced by the empty state. This can happen because no items exist, because filters remove them all, because the offset is past the end, or because a template page’s current item has no related items.

The default empty state is a grey box with the text "No items found". Design it for the visitor, not the editor.

One reported quirk is that a list’s native empty element renders only when the list has pagination on and at least two pages; if you rely on custom code to detect emptiness, test the real published page rather than the canvas.

The empty state is also where a defensive design places a call to action: an upcoming-events list with no future walks can read "No walks are scheduled; subscribe to hear about new ones", with a link to the newsletter form.

On a Collection template page it is common to show a few other items from the same Collection under the current item: "More plants from this zone", "Other articles". If the list is a plain dynamic list of the same Collection, the current item appears in it, which looks like a bug.

Webflow adds a filter for this on template pages. With the list selected, open Collection list settings, add a filter, choose the Collection’s name in the field dropdown, choose is not, and pick Current Collection item as the value. The list then excludes the page’s own item. Choosing is instead shows only the current item. The option appears for lists whose Collection matches the template page’s Collection; a list of a different Collection on the same page does not get it by default.

To build "More plants from this zone" on the plant template page:

The conditions combine with And, so the result is the plants in the same zone except this one, which is what the visitor expects.

All of the above is decided before the visitor arrives. A visitor-facing filter, such as "show only shade plants", "sort by bloom month" or a live search box, changes the displayed items in the browser, and Webflow’s native settings do not do that: the list’s filter and sort cannot be changed by the visitor at runtime. There are four ways to provide it.

A form that reloads the page. Webflow’s site search is a separate feature that returns search results pages; it does not filter an individual list. See Password Protection and Site Search.

Custom JavaScript over the rendered items. The items of a list are in the DOM, so a script can hide those that do not match. This works for the items that are rendered, which means up to 100 per list and only the current page of a paginated list. A small, dependency-free script that filters Fernbrook cards by a data attribute follows. The cards carry data-sun through a custom attribute bound to the Sun requirement field, and a set of buttons carry the value they select.

Source: Webflow Help Center: Collection list

The script lives in a Code Embed or in the page’s footer code; see Custom Code in the Head, Footer and Embeds and Custom Attributes and JavaScript. Because the filter hides cards with display, those cards are still in the HTML for search engines, which is usually desirable, but a screen reader user hears nothing for the hidden ones because display: none removes them from the accessibility tree.

A third-party attribute library. Several third-party libraries add filtering, sorting, "load more", combining of paginated lists and live search to Webflow lists by reading attributes you set on the elements. They are not Webflow products, their behaviour and licences change independently, and they run in the browser on the items that are in the page. Treat them as one option and compare them with a small script before adding a dependency; the Third-Party Libraries and Scripts page covers loading and risk.

The Data API from a headless front end. When the data set is large, or the filter must be server-side, render the lists in your own application from the Data API or the Content Delivery API and keep Webflow as the editing interface. This is the only approach that works beyond 100 items per request without paging in the browser.

An app built on the Designer API can create and configure lists. The element is exposed as a DynamoWrapper element, and its settings are read with getSettings() and written with setSettings(), which accepts a partial update and validates the whole update before applying any of it. The example configures the Fernbrook home-page strip.

Source: Designer API: Collection List settings

Points from the reference that matter when automating:

Pagination is configured the same way.

Source: Designer API: Collection List settings

Curated lists use queryMode: 'curated' with curatedItemIds, which needs item IDs found through the API’s item search. See Designer Extensions and the Designer API.

A Collection list is a configured view; the Data API returns the underlying items, which is what a headless front end, an export script or a sync job uses. A list of Plants with an explicit page size and offset reads, on a Developer workspace site, as follows. The token and the Collection ID come from the environment and are placeholders here.

Source: Data API: List Collection Items

The items/live endpoint returns published items, which is what a live Collection list shows; the plain items endpoint returns the staged items, including drafts. The default limit is 100 and its maximum is 100, matching the list limit, so a Collection with 350 items needs four requests with offsets 0, 100, 200 and 300. The response includes a pagination object with the total, which tells the client when to stop.

Source: Data API: List Collection Items

The loop respects the rate limit of the plan only if it is not run in parallel; see Data API: SDKs, Limits and Errors. For repeated reads, the Content Delivery API serves cached responses from a separate host and spares the rate limit, as explained in Content Delivery API and Headless.

Putting the settings together gives the lists of the running site.

Every block uses classes on the list and on the item and follows the naming system chosen for the site; see Class Naming Systems. The same card is worth building as a component with props, so that the home strip, the catalogue and the related block share it; a component used in a list item is described in Components, Props, Slots and Variants.

A list adapts with the breakpoints like any other layout; see Responsive Design and Breakpoints. The properties that matter are the grid template or the flex wrap on the list element, the gap, and the padding of the item. A catalogue that uses repeat(auto-fill, minmax(16rem, 1fr)) needs no breakpoint at all, because the column count follows the width.

Two behaviours are specific to lists. First, a smaller breakpoint cannot show fewer items by itself: the same items are rendered on every device, so hiding items with display: none on a small breakpoint still downloads them. If a mobile view must show three plants and a desktop view six, use two lists with different limits and show one per breakpoint, which costs both lists in the HTML, or use a script. Second, a slider element can contain a Collection list, in which case each item becomes a slide, but the slider’s navigation and the list’s pagination are independent.

The generated role="list" and role="listitem" give a screen reader the item count. Keep them. Give each card a single link with meaningful text, because a heading wrapped in a link block reads as one link, whereas separate "Read more" links on every card read as a row of identical links. Bind the image’s alt text to a field (a plain-text Image description field) instead of leaving it empty or repeating the name; see Accessibility. Pagination buttons are links with text, which is accessible by default; keep the text visible and do not replace it with an icon alone. A script that hides items for filtering should also announce the result, for example by updating a status region with the number of matches.

Tutorials written before the next-generation CMS describe a nested list that shows five items and a page with at most one or two nested lists; the Help Center now publishes higher figures for nested lists, as shown in the limits table. The 2021 book on Webflow describes Collection lists, filters, sort and pagination accurately for its time, and it correctly states that a visitor cannot change a list’s filter at runtime and that interactive filtering needs custom code or an attribute library; those statements are still true. Where its screenshots show the older Designer layout, the setting names are the same but the panels have moved. The full list of corrections is on Where Older Books and Tutorials Are Outdated.