Use reference fields to connect items from different Collections.
The reference field is a Collection field that you can add to a CMS Collection. Instead of using an option field which only lets you choose from a list of predefined values, the reference field lets you choose from any item in another Collection. You can then use the referenced item’s data in Collection lists and Collection pages.
For example, there may be a text field on a Collection page that is dynamically linked to a Collection called “Recipes”. Then, a Collection item (e.g., an author) in a Collection called “Authors” can be referenced in the “Recipes” Collection via a reference field.
If the author is connected to the “Recipes” Collection page via a reference field, and you update that author’s information down the road, it will automatically update on the Collection page because of the reference field connection.
Some common uses for the reference field include:
- A “Blog posts” Collection referencing an “Authors” Collection
- A "Recipes" Collection referencing an "Authors" Collection
- A "News articles" Collection referencing a "Category" Collection
- A "Lessons" Collection referencing a "Courses" Collection
Note
To reference multiple items in a Collection (e.g., referencing two author's names), use the multi-reference field.
Reference field limits
The number of reference fields you can add to new or existing Collections depends on your plan.
-
Enterprise plans — can add up to 20 reference fields per Collection
-
Non-Enterprise plans — can add up to 10 reference fields, depending on the site plan. To check how many references fields are available, go to Site settings > Plans > All site features.
How to create a reference field
To add a reference field to an existing Collection:
- Hover over the Collection you want to add the reference field to
- Click the settings “cog” icon to open the Collection settings
- Click Add new field in the Collection fields section
- Select the Reference field type
- Add a Label
- Add Help text, if you want
- Select a Collection to reference from the Collection dropdown
- Choose “This field is required” if you want the field to be required
If you don’t have a Collection yet, learn how to add a Collection to your site.
How to reference items
Once a reference field is added to a Collection, you can go into that Collection’s Collection items and set a value for the field in each Collection item. There, you can choose any item from the other Collection you’re referencing in the reference field settings.
How to use the reference field in your site design
You can pull data from a referenced Collection and add it to a Collection page or a Collection list in your site’s design. You can connect a field to an element or to a style.
Connecting elements
When you add any element into a Collection list or onto a Collection page, you can get the content for that element from a referenced Collection’s fields.
For example, you can connect a recipe’s name in your Recipe Collection to a Heading element, and an author’s name to a text element.
Connecting styling
If a referenced Collection has a color field or an image field set on each Collection item, you can use these fields to style an element’s background color, border color, text color, or background image in your site’s design.
How to filter a Collection list using the reference field
There are 3 ways to use a reference field to filter Collection lists. For our examples, we’ll use a “Recipes" Collection that references an "Authors" Collection.
- Filter by a specific Collection item that’s in the referenced Collection (e.g., show only the recipes that reference a specific author)
- Filter by the current page’s reference (e.g., show a list of other recipes that have the same author as the author on the current page)
- Filter by the current page’s reference on the referenced Collection page (e.g., on the Authors Collection page, show all recipes that reference that author)
Important
Filtering by reference fields is only available for Collection lists that are connected to a Collection with a reference field.
How to filter by a specific item that’s in the referenced Collection
You can filter Collection lists by using the reference field. This allows you to show specific items that meet the filter rule.
One real-world example of this could be creating a Collection list called “Featured recipes.” You can filter this Collection list so that it references only the Collection items (the recipes) in a “Recipes” Collection that has a ‘featured’ toggle switched on.
Filter by current page’s reference
You can add a Collection list to a Collection page and have it only show the items that have the same referenced item as the Collection page’s referenced item.
For example, on a "Recipes" Collection page you can show a list of other recipes that have the same author referenced as the current page’s author. This is also a common way to display “Related content” sections.
To do this, you would add a filter to the current page’s Collection list where the “Author” reference field equals “Author of Current Recipe.”
Filter by current page’s reference on the referenced Collection page
You can also filter a Collection list on the referenced Collection page.
For example, on your "Authors" Collection page, you can show all recipes (from a “Recipes” Collection) that reference that author. To do this, add a Collection list and connect it to the “Recipes" Collection. Then, add a filter to this Collection list where the “Author” reference field equals the “Current Recipe Author.”
Learn more about Collection list filters.
Show or hide elements based on a reference field
You can use conditionals to show or hide elements in a Collection list or on a Collection page using:
Where can you use this type of conditional?
You can create this type of conditional only when the selected element is:
inside a Collection list connected to the Collection that contains the reference field, or
on the Collection page (template page) for that Collection
For example, if you have a Collection called “Events” that has a reference field linked to a Collection called “Locations”, you can add conditionals based on the “Location” reference field or fields from the referenced “Locations” Collection in the following places:
What kind of conditionals can you set?
You can add the following conditionals based on the reference field itself:
You can also create a conditional based on a field from the referenced Collection. The available rules depend on the type of field you choose (for example, text, switch, number, etc.).
Example: A conditional based on a field from a referenced Collection
In this example, we have a Collection list connected to an “Events” Collection. The “Events” Collection references a “Locations” Collection.
In the Collection list connected to “Events”, we’ve connected values from the “Locations” Collection to elements (for example, City, Date, etc.). We can set a conditional on an element so it only appears when the referenced field value is set:
Select the element to show or hide (must be inside a Collection list or on a Collection page)
Go to Element settings > Visibility
Click the “plus” icon
Choose the field from the referenced Collection (for example, “City (Location)”)
Choose Is set
Set Visibility to Visible
Set Else > Visibility to Hidden
Click off the modal or press Esc to save the conditional
In this example, we also have a “Map link” that we want available when a map link exists. If some locations don’t have a map link, we don’t want to show a link when there’s nowhere to go.
We can add a conditional to the Text link so it shows only when the referenced “Map link” field is set. Then, we can add a Text block (instead of a Text link) and connect it to the “City” field. Set a conditional on the Text block for when the “Map link” field Is not set — this way, only the city name (without a link) appears when there’s no map link.
Example: A conditional based on the reference field
In this example, we’ve added all location-related labels and values inside a div block styled under the class name “Location details.” Using conditionals, we can make sure this entire div block only appears when the “Location” reference field is set for each event:
Select the “Location details” element (must be inside a Collection list or on a Collection page)
Go to Element settings > Visibility
Click the “plus” icon
Choose the reference field (for example, “Location (Reference)”)
Choose Is set
Set Visibility to Visible
Set Else > Visibility to Hidden
Click off the modal or press Esc to save the conditional
Note
The reference field cannot be used for sorting.