Multi-reference field

A multi-reference field is similar to a reference field, except it allows you to reference more than one item from another Collection and then present these items in a Collection list on a Collection page. This is great for tagging systems and instances where you want to connect one item to many others.

Some common uses for a multi-reference field include:

• A “Blog post” Collection referencing multiple authors from an “Authors” Collection
• A “Projects” or “Recipes” Collection referencing multiple tags in a “Tags” Collection

In this lesson, you’ll learn:

1. How to create a multi-reference field
2. How to reference items from a multi-reference field
3. How to use the multi-reference field in your design
4. How to filter a Collection list using the multi-reference field
5. How to set conditional visibility using the multi-reference field
6. Answers to common questions about the multi-reference field

How to create a multi-reference field

The beauty of the reference and multi-reference fields is that whenever you edit an item that’s being referenced, the new content will automatically update everywhere it’s referenced. For example, if you update a blog post's name, every reference to that blog post will also update automatically.

To add a multi-reference field to a Collection:

1. Hover over the Collection you want to add the multi-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 Multi-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.

How to reference items from a multi-reference field

Once you've added a multi-reference field to a Collection’s settings, you can go into your Collection items and start adding the referenced items. You can choose to reference multiple Collection items from the Collection you chose in the multi-reference field settings.

How to use the multi-reference field in your design

To use multi-reference fields in your site pages:

1. Go to the Collection page for the Collection that has the multi-reference field
2. Add a Collection list to the Collection page from the Add panel
3. Connect the Collection list to the multi-reference field

Now, you can add elements and styles to the Collection list and connect those to the multi-reference field. This lets you dynamically pull information from Collection items that are referenced by the multi-reference field.

Connect the multi-reference field to a Collection list

In this example, we have a “Recipes” Collection with a multi-reference field that’s referencing a "Tags" Collection. We added a Collection list onto the “Recipes” Collection page and connected it to the "Tags" multi-reference field.

Important: Make sure you connect the Collection list to the multi-reference field and not the actual Collection that is referenced. If you connect to the actual Collection, it will pull all the Collection items in that Collection instead of only the referenced ones.

Connect elements and styles to fields from the referenced collection

When we add an element (e.g., a Heading, Paragraph, Image, etc.) to this Collection list, we can pull the content for that element from any of the referenced Collection’s fields. For example, you can connect a tag’s name to a Heading element or connect a tag’s icon in an image element.

How to filter a Collection list using the multi-reference field

Let's say you have a “Recipes” Collection that has a multi-reference field connected to a "Tags" Collection. You can use the "Tags" multi-reference field to filter Collection lists that are connected to the "Tags" Collection on both the "Recipes" and "Tags" Collection pages.

How to show all items that contain the current referenced field

For example, you can show all "Recipes" that reference a tag on the "Tags" Collection page (e.g., showing all recipes that reference a “sandwich” tag). To do this:

1. Go to the “Tags” Collection page
2. Add a Collection list and connect it to the "Recipes" Collection
3. Select the Collection list and go to Element settings > Filters
4. Click the “plus” icon to the right of Filters
5. Add a filter rule: “Tags” contains “Current Tag”
6. Click Save

Show all items that contain any referenced field of the current item

Let's say, on the "Recipes" Collection page, you want to display a list of all related recipes that have any of the same tags as the recipe you’re currently viewing. To do this:

1. Go to the “Recipes” Collection page
2. Add a Collection list and connect it to the "Recipes" Collection
3. Select the Collection list and go to Element settings > Filters
4. Click the “plus” icon to the right of Filters
5. Add a filter rule: “Tags” contains “Any Tags of Current Recipe”
6. Click Save

How to set conditional visibility using the multi-reference field

You can set conditional visibility — using the multi-reference field — to show or hide individual elements in a Collection list or on a Collection page.

This type of condition can only be created in two places:

• Within a Collection list that's connected to the Collection that contains the multi-reference field
• On the Collection page of the Collection that contains the multi-reference field

For example, if you have a Collection called “Recipes” that has a multi-reference field linked to a Collection called “Tags”, you can add conditions based on the reference field “Tags” in any Collection list that is connected to the “Recipes” Collection as well as on the “Recipes” Collection page.

You can add the following conditions based on the multi-reference field:

• When the multi-reference field Contains or Does not contain a specific value
• When the multi-reference field Is set or Is not set

Show content when a multi-referenced field is set

Let’s say we want to add an “Author” section under each recipe on the “Recipe” Collection page. We can do that by adding a Collection list and connecting it to an “Author” multi-reference field.

Now, what if we want this section to appear only when there are authors set in the multi-reference field? We need to set a condition on the section like this:

1. Select the Section
2. Go to Element settings > Conditional visibility
3. Click the “plus” icon to the right of Conditions
4. Select your multi-reference field (e.g., “Authors”) in the first dropdown
5. Choose Is set in the second dropdown
6. Click Save

Answers to common questions about the multi-reference field

Why can't I add a reference field?

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.

Why can’t I filter and sort Collection lists connected to a multi-reference field?

There’s no filtering and sorting options for Collection lists because they automatically show the referenced items for that page in the order that you've selected them within the multi-reference field (in the Collection item settings).