Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form
Trusted by teams at
Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form
Use reference fields to connect items from different Collections.
Note: We're transitioning to Workspaces, and are in the process of updating our content. Visit the blog post to read more about these updates and changes.
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.
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.
In this field’s settings, you can choose which Collection you want the current Collection to reference.
Like with other fields, you can also specify the label, help text and if the field is required to publish.
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.
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.
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.
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.
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.
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.
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.
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:
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 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:
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.
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:
The reference field cannot be used for sorting.
