Reference and Multi-reference Fields
|
This content was generated with the assistance of AI and should be verified against the official Webflow documentation before being relied on in production. This sub-section’s Webflow bibliography lists the reference material consulted while preparing these pages. |
This page describes Reference and Multi-reference fields as they were on 2026-10-28, the date on which its facts were checked against the official documentation. Both field types exist on every plan that includes the CMS; the number of Collections and items that a site can hold depends on the plan tier (Starter, Basic, Premium, Team or Enterprise), and the CMS Limits and Scaling page lists them. Webflow has no version numbers, so changes after the check date are tracked in Product Changes and Deprecations.
A Collection on its own is a flat table. Reference fields turn a set of Collections into a small relational model: an item points to an item of another Collection (or of the same one) instead of copying its content. The running example, Fernbrook Gardens, needs this everywhere. A plant grows in one Zone, a Garden Journal post is about several plants, and a plant has several companion plants. This page shows how to model each relationship, how to display the related data, and where the limits are. The field types as a whole are covered in Collections and Field Types, the modelling method in CMS Concepts and Content Modeling.
The two field types
| Reference | Multi-reference | |
|---|---|---|
Cardinality |
Points to one item of the target Collection |
Points to any number of items of the target Collection |
Typical relationship |
many-to-one (many plants, one zone) |
many-to-many (posts and plants, plants and companions) |
Editor control |
A drop-down that selects one item |
A multi-select that picks and orders several items |
Value through the Data API |
A single item ID string |
An array of item ID strings |
Fernbrook example |
|
|
A rule of thumb from Webflow University is to describe the relationship as a plain sentence, decide whether it involves one item or several, and put the field in the Collection where the editors choose the connection. Webflow’s University lesson adds that a multi-reference field is the right choice whenever a relationship can involve more than one item, even if only one is connected today, because changing a field’s type later is not possible: a field cannot be converted, so the fix is to add a new field, rebind the design, copy the data and delete the old field.
Modelling relationships
One-to-many: a Reference field
A zone has many plants, a plant is in one zone. The field lives on the "many" side. Plants gets a Reference field
named Zone that targets the Zones Collection. Updating a Zone’s name, map image or opening hours once changes every
plant page that shows it, because the plant stores a pointer and not a copy.
Build order matters, and the University lesson states it: the target Collection must exist before the field can point to
it, and the target items should exist before the editors connect them. For Fernbrook the sequence is: create Zones and
its items (Rose Garden, Alpine Slope, Tropical House), add Plants.zone, then fill in each plant.
Many-to-many: a Multi-reference field
A journal post is about several plants and a plant appears in several posts. Webflow has no join table: one side holds
a Multi-reference field, and the other side is answered with a filter (see below). Put the field on the side the editors
work from. Fernbrook editors write posts, so Garden Journal.plants is a Multi-reference field targeting Plants.
Self-reference: companions
A reference field can target its own Collection. Plants.companions is a Multi-reference field that targets Plants,
so each plant lists the plants that grow well beside it. The Data API documentation notes that the target may be a
different Collection or the same one.
| Collection | Field | Type | Target and meaning |
|---|---|---|---|
Plants |
|
Reference |
|
Plants |
|
Multi-reference |
|
Plants |
|
none |
Not stored; answered by filtering |
Garden Journal |
|
Multi-reference |
|
Events |
|
Reference |
|
The reverse direction
Relationships are stored on one side only, yet both sides can display them. Webflow’s University lesson makes the point
directly: you do not need a reverse field to show the relationship from the other side. A Zone page lists its plants with
a Collection list of Plants filtered by Zone equal to the current Zone, and a plant page lists the posts about it
with a Collection list of Garden Journal filtered by Plants contains the current Plant. Adding a second field on the
other side would duplicate the data and let the two drift apart.
Editing referenced items
In the Collection item panel a Reference field shows the items of the target Collection, and a Multi-reference field lets the editor add several. An item can be created from the panel of the Collection that holds it, and the editor can open a referenced item from the field to edit it. The values the editor can choose are the target Collection’s items; the Collection that holds the field must therefore be created after, or at least linked to, the target.
Three behaviours are worth knowing before the first import.
-
Draft and archived targets. A reference stores the target item’s ID. A published page can only display data of a published target item, so a plant that points to a draft Zone shows an empty zone on the live site until the Zone is published. Publish the target Collection’s items first, or publish both together.
-
Deleting a target. Deleting an item that others reference leaves those fields empty. Check where an item is used before removing it, and consider archiving instead.
-
Slugs and renames. A reference stores the ID, not the name or the slug, so renaming a Zone or changing its slug does not break any link. Only the URLs of the Zone page change, and Webflow does not create a redirect for you, so add a 301 redirect (see Redirects and Site Migration).
Binding referenced data
On a Collection page
On a Collection template page the Collection’s own fields are available directly, and so are the fields of the item a
Reference field points to. Select a text element, open the bind menu and choose the Reference field first; Webflow then
offers the fields of the target Collection. On a Plant template that gives Zone > Name, Zone > Map image and
Zone > Slug, and a link block can point to the Zone’s template page through Zone. Only the fields of a single-reference
target are available this way: the data of one referenced item is used as if it were part of the current item.
Collection Template Pages covers template pages in depth.
Multi-reference fields are displayed with a list
A Multi-reference field holds several items, so it cannot be bound to one text element. It is displayed with a
Collection list: add a Collection list to the template page, and on its settings choose the Multi-reference field as
the source, such as Plants > Companions. The list then renders one list item per referenced plant, and inside it every
field of the target Collection is available. Because this list sits inside a list item or a template page it is called a
nested list when it is placed inside another Collection list.
The generated markup
Webflow renders a Collection list as a wrapper that carries w-dyn-list, a list element with w-dyn-items, and one item
per entry with w-dyn-item. An empty list shows the element marked w-dyn-empty instead. The sketch below shows the
structure of the "Companions" list on a Rose plant page; the IDs, ordering and extra classes Webflow adds vary, and the
class names after the first are the designer’s own.
<div class="companions_list w-dyn-list">
<div role="list" class="companions_items w-dyn-items">
<div role="listitem" class="companions_item w-dyn-item">
<a href="/plants/lavender" class="companions_link w-inline-block">
<img src="https://cdn.prod.website-files.com/PLACEHOLDER/lavender.jpg" alt="Lavender in flower" class="companions_img">
<div class="companions_name">Lavender</div>
</a>
</div>
<div role="listitem" class="companions_item w-dyn-item">
<a href="/plants/catmint" class="companions_link w-inline-block">
<img src="https://cdn.prod.website-files.com/PLACEHOLDER/catmint.jpg" alt="Catmint border" class="companions_img">
<div class="companions_name">Catmint</div>
</a>
</div>
</div>
<div class="w-dyn-empty">
<div>No companions listed yet.</div>
</div>
</div>The w-dyn-empty block is the empty state, edited on the canvas as a separate element. Provide a useful message, or
use conditional visibility (see Conditional Visibility
and Dynamic Embeds) to hide the whole section when a field is empty, so that no heading hangs over nothing.
Filtering by reference
A Collection list can be filtered on a Reference or Multi-reference field. The comparison depends on the type.
| Field type | Typical filter | Result |
|---|---|---|
Reference |
|
Items whose zone is this zone |
Reference |
|
A curated list on any page |
Multi-reference |
|
Posts that mention this plant |
Multi-reference |
|
Plants that list this plant as a companion |
Either |
|
Items that have, or lack, a connection |
The University lesson gives the same pattern in its own words: a Service page can list the locations that offer it with
a Collection list filtered by "Services contains Current Service". Filters can be combined with and and or conditions,
sorted, limited and paginated; those options and the 100-item default are covered in
Collection Lists.
The current item context
On a template page, "current item" refers to the Collection item the page was generated for. Inside a Collection list
that is bound to another Collection, the same filter value is still the template page’s item, not the list item being
rendered. This is the mechanism behind every "related" block, and it is how the other items list works: filter
Plants by Zone equal to the current Zone, then exclude the current plant with the "exclude current item" option the
list offers on a template page, so the plant being viewed does not recommend itself.
The same mechanism cannot be reused outside a template page. A static page has no current item, so a filter against it can only compare with a fixed item. A multi-reference field of an item can also only be displayed in a list placed in a context that knows the item, which is why forum threads describe the field as working well only inside a Collection template: the supported alternative on a plain page is a list filtered by a fixed item, or a custom script that uses the Data API.
Visitor-driven filtering
Native filters are decided by the designer and fixed at publish time; visitors cannot change them. "Show only plants for this zone" as a menu on a page needs custom code or one of the attribute-based filtering libraries. The structure above helps with that: each list item can expose its reference data in a custom attribute or a CMS-bound class so the script has something to match. See Custom Attributes and JavaScript.
Limits
Reference fields are limited, and so are the nested lists that display them. The University lesson states that both have limits and tells readers to check the current numbers, and the numbers below are the ones recorded on the check date; confirm them before building a large model.
| Limit | Value on 2026-10-28 |
|---|---|
Reference plus Multi-reference fields per Collection |
10 (20 on Enterprise) |
Fields of all types per Collection |
60 (100 on the Enterprise next-gen CMS) |
Collection lists per page |
40 |
Nested Collection lists per page |
10 |
Items shown by one nested list per parent item |
100 |
Items shown by a Collection list by default |
100 |
Design with these numbers in mind. A Collection that needs more than ten relationships usually models more than one thing; split it, or replace several Multi-reference fields with one Option field when the values are a fixed short vocabulary and need no page of their own. Because nested lists are capped at ten per page, a page that shows companions, related posts, events and zone members for each of many parent items will hit the ceiling; show the extra relationships in separate lists filtered by the current item rather than nested inside a parent list.
CMS Limits and Scaling explains what to do when a site approaches them, including moving heavy relationships to a headless front end.
Reference fields in the Data API
The Data API v2 creates and fills both field types. The field definition names the target Collection in
metadata.collectionId, and the item value is an ID or an array of IDs. The examples use a Developer workspace site;
the IDs are placeholders and the token comes from an environment variable.
Defining the fields
# Add a Reference field "Zone" to the Plants collection
curl -X POST "https://api.webflow.com/v2/collections/$PLANTS_COLLECTION_ID/fields" \
-H "Authorization: Bearer $WEBFLOW_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"type": "Reference",
"displayName": "Zone",
"helpText": "Where the plant grows",
"metadata": { "collectionId": "ZONES_COLLECTION_ID_PLACEHOLDER" }
}'
# Add a Multi-reference field "Companions" that points back to Plants
curl -X POST "https://api.webflow.com/v2/collections/$PLANTS_COLLECTION_ID/fields" \
-H "Authorization: Bearer $WEBFLOW_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"type": "MultiReference",
"displayName": "Companions",
"helpText": "Plants that grow well beside this one",
"metadata": { "collectionId": "'"$PLANTS_COLLECTION_ID"'" }
}'Setting values
Item values use the field’s slug as the key. A Reference value is one item ID string, and a Multi-reference value is an array of item ID strings. The IDs come from the Get Items call of the target Collection.
{
"fieldData": {
"name": "Rose",
"slug": "rose",
"zone": "ZONE_ITEM_ID_PLACEHOLDER",
"companions": [
"LAVENDER_ITEM_ID_PLACEHOLDER",
"CATMINT_ITEM_ID_PLACEHOLDER"
]
}
}The order of the array is the order in the field, so it decides the order of a list that is sorted by the field’s own order. Import the referenced Collection first and keep a map from your own keys to the IDs Webflow returned, because the IDs of the target items are needed before the dependent items can be written. The managing-items guide covers staged and live items and publishing.
Reference fields in CSV import and export
In a CSV file a reference column holds the identifying value of the target item, and a Multi-reference column lists several of them separated by semicolons on import. Exports separate the values with commas. Import the target Collections first, and take a backup before a large import. See CSV Import and Export.
Pitfalls
-
Duplicate names in the target. Keep the names of referenced items unique, so that a CSV reference cannot match two items.
-
Nested lists that look empty. A nested list cannot show more than its documented cap per parent, and it shows nothing when the parent’s reference field is empty or points to unpublished items.
-
Referencing the wrong Collection. The target Collection is fixed when the field is created. To change it, add a new field and migrate.
-
Too many fields. Reaching ten reference fields in a Collection stops further additions; plan relationships early.
-
Expecting a reverse field. There is none; filter the other Collection by the current item instead.
-
Choosing Reference when the relationship will grow. A single Reference cannot become a Multi-reference, so decide using the University rule above.
-
Confusing references with Option fields. An Option field is a fixed list that belongs to one field and has no pages, no extra data and no sharing; use a Collection and a reference when values need their own page or attributes.
What older books and tutorials say
Older tutorials describe reference fields with the 2021 Designer: the field limits they quote differ, and the bind menu and list options look different. The concepts are unchanged, but check the limits in the table above and the current Collection list settings rather than copying numbers from a book. The book used as a reference for this sub-section does not cover reference fields at all, so these relationships are learned from the official documentation only. See Where Older Books and Tutorials Are Outdated.