Use reference fields to connect items from different Collections.
Note: We’re transitioning to Workspaces, and this lesson has been updated to reflect that change. Visit the Workspaces blog post to read more about these updates and changes.
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:
In this lesson you’ll learn:
You can add a reference field to a new or existing Collection. To add a reference field to an existing Collection:
If you don’t have a Collection yet, learn how to add a Collection to your site.
Important: You have a limited number of reference fields per Collection depending on your Site plan. Starter, CMS, and Ecommerce Standard Site plans can have up to 5 reference fields per Collection. Business, Ecommerce Plus, Ecommerce Advanced, and Enterprise Site plans can have up to 10 reference fields per Collection. Basic Site plans do not offer reference fields. Learn more about site plans.
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.
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.
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.
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.
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.
Important: Filtering by reference fields is only available for Collection lists that are connected to a Collection with a reference field.
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.
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.”
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.”
You can set conditional visibility to show or hide individual elements in a Collection list or on a Collection page using:
This type of condition can only be created within a Collection list that's connected to the Collection containing the reference field or is on the Collection template page of this Collection.
For example, if you have a Collection called “Events” that has a reference field linked to a Collection called “Locations”, you can add conditions based on the reference field “Locations” or any fields from this referenced collection in the following places:
You can add the following conditions based on the reference field itself:
You can also create a condition based on a specific field from the referenced collection. The type of condition depends on the type of the Collection field.
In this example, we have a Collection list connected to an "Events" collection. The “Events” Collection references a “Locations” collection.
In this Collection list connected to the “Events” collection, we have a number of field values from the "Locations" Collection connected to text blocks. We've added labels for each value we want to show (i.e., "Date", "City", etc.). The labels and the values have a display set to inline so they appear side by side.
We can set conditional visibility on a text block so it only appears when the value is set in the Collection item:
In this example, we also have a “Map link” which we want available to site visitors when they click the city name. To do that, we're using a Text link that pulls the text from the "City" field and the URL from the "Map link" field.
If some locations don’t have a map link, we don’t want to show a text link when there’s no link to go to. In this case, we can use conditional visibility.
We can add a condition to this Text link so it shows only when the "Map link" field of the referenced "Locations" Collection Is set (e.g., when a map link has been added to the Collection item).
Next, we can add a Text block (instead of a Text link) and connect it to the “City” field. Then we can set a condition of this Text block for when the "Map link" field Is not set. This way, only the city name (without a link) will show up when there is no “Map link” set in the “Locations” Collection item.
To ensure the Text block is inline with the label, you can add a class to it and set the display to inline.
We’ve added all these location-related labels and values inside of a div block, which we styled under the class name “Location details.” Using conditional visibility, we can make sure this entire div block only appears when the “Location” reference field is set for each event in the “Events” Collection. To do this: