Reference field

The reference field is a Collection field that you can add to any of your Collections. Instead of using an option field and choosing from a list of predefined values, the reference field allows you to choose from any item from another Collection. You can then use the referenced item’s data in Collection lists and Collection pages.

For example, each blog post may have an author. If you edit an author’s information down the road, it will automatically update on the blog post because of the connection that’s created via this reference field.

Common uses

• "Blog posts" Collection referencing an "Authors" Collection
• "Articles" Collection referencing a "Category" Collection
• "Lessons" Collection referencing a "Courses" Collection

To reference multiple items from a different Collection, use the multi-reference field.

In this lesson

• Creating a reference field
• Referencing items
• Using the reference field in your design
• Filtering a Collection list using the reference field
• ‍Setting conditional visibility using the reference field

Creating a reference field

A reference field can be added to a new or existing Collection. In Collection settings, click on New Field and then choose the Reference field.

Choose a Collection to reference

In this field’s settings, you can choose which Collection you want the current Collection to reference.

Other field settings

Like with other fields, you can also specify the label, help text and if the field is required to publish.

Need to know

You get a limited number of references per Collection depending on the type of account plan you're on, or the type of Site plan you've purchased for your project.
‍
All free or paid account plans can have up to 5 references per Collection per unhosted project. Projects with a CMS or Standard Ecommerce site plan can also have up to 5 references per Collection. Projects with a Business, Plus, or Advanced Ecommerce site plan can have up to 10 references per Collection.

Referencing items

Once a reference field is added to the Collection, you can go into your Collection items and set a value for the field. You can choose any item from the Collection you chose in the reference field settings.

Using the reference field in your design

You can pull data from a referenced Collection in a Collection page or a Collection list. 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 any of the referenced Collection’s fields. 

For example, you can connect a category’s name to a heading element and the tag’s icon to an image element.

Connecting styling

If the referenced Collection has a color field or animage field, you can use these fields to style any element’s background color, border color, text color, or background image.

For example, if a category Collection has a color set on each item, when referencing this Collection on blog posts you can color sections, background, or any other element with that color.

Filtering a Collection list using the reference field

There are three powerful ways to use the reference field to filter Collection Lists. For our examples, we’ll be using a "Blog posts" Collection that references a "Category" Collection.

1. Filter by a specific item that’s in the referenced Collection (e.g. Show only the Blog Posts that reference a specific Category)
2. Filter by current page’s reference (e.g. Show a list of other Blog Posts that have the same Category referenced)
3. Filter by current page’s reference on the referenced Collection page (e.g. on the Category Collection page, show all Blog Posts that reference that Category)

Need to know

Filtering by reference fields is only available for Collection lists that are connected to a Collection with a reference field.

Filter by a specific item that’s in the referenced Collection

The reference field can be used to filter Collection lists to show specific items that meet the filter rule. You may want to create a Collection list that displays only items that reference an item from the referenced Collection.

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 page’s referenced item. For example, on your "Blog posts" Collection page you can show a list of other "Blog posts" that have the same "Category" referenced as the current page. This is common for displaying “related content” sections. To do this, add a filter to this  Collection list where the Category reference field equals current Collection.

Filter by current page’s reference on the referenced Collection page

In the above example, we filtered a Collection List on the same Collection page, but you can also filter a Collection list on the referenced Collection page. For example, on your "Category" Collection page, you can show all "Blog posts" that reference that Category.

To do this, add a Collection list and connect it to the "Blog posts" collection. Then, add a filter to this Collection list where the Category reference field equals current Collection.

Learn more about Collection list filters

Setting 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 or any fields from the referenced collection.

Where can you use this type of conditions?

This type of condition can only be created within a collection list that's connected to the collection that has the reference field or 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 doesn’t 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 - condition based on a field from a referenced collection

In this example, we have a collection list connected to a "Events" collection. This collection references a “Locations” collection.

In this collection list, 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: "City", "Date", and "Phone". The labels and the values have a display setting set to inline so they appear side by side.

Now, let’s set conditional visibility on each of these labels so they only show when the value is set:

1. Select a label, for example "City"
2. Add a condition in the settings panel
3. Choose the field from the referenced collection in the first dropdown, for this example that would be City (venue).
4. Choose is set in the second dropdown

Do the same for all the other labels.

Now, we also have a “map link” which we want our users to access by clicking 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.

Now, what if some locations do not have a map link? We don’t want to show a text link when there’s no link to go to. So, what we can do is add a condition to this text link to show only when the "map link" field of the referenced "locations" collection is set.

Then, we add another text block and connect it to the “city” field and set the condition of this element to when the "map link" field is not set.

To ensure that the text block is inline with the label, add a class to it and set the display setting to inline.

Example — condition based on a referenced field

Now, since we’ve added all these location related labels and values inside of a div block styled it under the class name: “Location details”. We want to make sure that this div block only appears when the location reference field is set for each event. To do that:

1. Select the “Location details” div block
2. Add a condition under the conditional visibility section in the settings panel
3. Select your reference field, Location (reference), in the first dropdown
4. Choose Is set in the second dropdown
5. Save

Must know

The reference field cannot be used for sorting.