Reference field overview

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 different Collection (e.g., referencing an author’s name and bio), use the multi-reference field.

In this lesson you’ll learn:

1. How to create a reference field
2. How to reference items
3. How to use the reference field in your site design
4. How to filter a Collection list using the reference field
5. How to set conditional visibility using the reference field

How to create a reference field

You can add a reference field to a new or existing Collection. To add a reference field to an existing Collection:

1. Hover over the Collection you want to add the reference field to
2. Click the settings “cog” icon to open the Collection settings
3. Click Add new field in the Collection fields section
4. Select the Reference field type
5. Add a Label
6. Add Help text, if you want
7. Select a Collection to reference from the Collection dropdown
8. 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.

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.

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.

How to set conditional visibility using the reference field

You can set conditional visibility to show or hide individual elements in a Collection list or on a Collection page using:

• The reference field itself
• Any fields from the referenced collection

Where can you use this type of condition?

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:

• In any Collection list that is connected to the “Events” Collection
• On the “Events” template page

What kind of conditions can you set?

You can add the following conditions based on the reference field itself:

• When the reference field Is set or Is not set
• When the reference field Equals or Does not equal a specific value

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.

Example: A condition 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 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:

1. Select the text block (e.g., "City")
2. Open Element settings panel > Conditional visibility
3. Click the “plus” icon to the right of “Conditions”
4. Choose the field from the referenced collection in the first dropdown — for this example that would be City (Location)
5. Choose Is set in the second dropdown
6. Save the condition

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.

Example: A condition based on a referenced field

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:

1. Select the “Location details” div block
2. Open Element settings panel > Conditional visibility
3. Click the “plus” icon to the right of “Conditions”
4. Select your reference field (e.g.,“Location (Reference)”) in the first dropdown
5. Choose Is set in the second dropdown
6. Save the condition

Note: The reference field cannot be used for sorting.