Oops! Something went wrong while submitting the form
The UI in this lesson may seem different if you've enables the Style Panel Beta! This content will be updated soon!
This video features an old UI. Updated version coming soon!
This video features an old UI. Updated version coming soon!
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.
"Blog posts" Collection referencing an "Authors" Collection
"Articles" Collection referencing a "Category" Collection
"Lessons" Collection referencing a "Courses" Collection
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.
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.
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.
Filter by a specific item that’s in the referenced Collection (e.g. Show only the Blog Posts that reference a specific Category)
Filter by current page’s reference (e.g. Show a list of other Blog Posts that have the same Category referenced)
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.
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:
Select a label, for example "City"
Add a condition in the settings panel
Choose the field from the referenced collection in the first dropdown, for this example that would be City (venue).
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:
Select the “Location details” div block
Add a condition under the conditional visibility section in the settings panel
Select your reference field, Location (reference), in the first dropdown
Choose Is set in the second dropdown
The reference field cannot be used for sorting.
Can I Use ?
Data on support for the feature across the major browsers from caniuse.com.