Multi-reference field

A multi-reference field allows you to associate one item with multiple others from another Collection, which is great for tagging and categorization.

This video features an old UI. Updated version coming soon!

A Multi-Reference field (which is short for multi-item reference field) does just that. Instead of a Reference field, which lets us pick one item from another collection, a Multi-Reference lets us pick multiple items.

So we have our blog posts. And we have our author at the top of each post. Now Helen is known throughout the industry for hogging the limelight. However, in a new initiative, we decided to credit other contributors to our blog posts.

So we have a little spot on the bottom for contributors. This is all static content right now — it's just the design. Nothing's been added yet from our collection.

Let's go into the CMS, into our Blog Posts collection, and, of course, Settings. All we have to do? Is click multi-reference. We can name the field Contributors, we can add some clarifying help text so anyone else using the CMS or the Editor knows what to do, but the important part here is that we point our multi-reference field to our Authors collection. Here's why:

If we save, and then go into our any of our items, like this blog post (by Helen), we can now see our multi-reference field. And all we have to do? Is choose from the list — the other authors who contributed to this post. Once we've done that, let's save.

Now we've only done this on one post so far, we can go back and fill the rest in later. So we're going to build this using the blog post we just configured.

Let's drag in a collection list so we can list the contributors. And from the Collection dropdown, we can see our brand-new field right there.

Notice how the authors already show up in the list. And from here, this is just like a normal collection list. Let's go over to our Elements panel and grab a heading. We can drag it right into any item, and of course, we'll get the text from our collection.

Our authors are showing up just fine. Warp speed. Actually we're just changing the velocity of the footage we captured so you don't have to watch us tweak every detail.

Alright Dale, let's take it down to normal. Dale. Dale! Okay, we're fast-forwarding through the entire— can we? Thank you, Dale.

So we just finished setting up our contributors in this collection list. And if we go back into the CMS? And we add contributors to another item in our collection? Another blog post? We have our multi-reference field from which we can select our contributors. We can add as many as we'd like.

And once we're done, let's save. And then go back to our collection page. And from the item dropdown, let's pick that blog post we just configured. And at the bottom? We have all our contributors showing up in the collection list.

And that's it! Multi-reference fields give us access to multiple items in another collection.

This video features an old UI. Updated version coming soon!

A multi-reference field is just like 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 other instances where you want to connect one item to many others.

Common uses

Blog post Collection referencing multiple authors from an Authors Collection
Projects Collection referencing multiple tags in a Tags Collection

In this lesson

Create a multi-reference field
Reference items from a multi-reference field
Use the multi-reference field in your design
Filter a Collection list using the multi-reference field
Set conditional visibility using the multi-reference field

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. So, for example, if I updated a related blog post's name, every reference to that blog post will update automatically.

To add a multi-reference field to a Collection, click New Field and then choose the multi-reference field.

Set up the multi-reference field

In multi-reference field’s settings, choose which Collection you want the current Collection to reference. You can also specify the name, help text, and whether the field is required to publish.

Reference items from a multi-reference field

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

Use the multi-reference field in your design

To use multi-reference fields in your designs, connect a Collection List to this field in a Collection Page that has that field. You can then connect to elements and styles inside this Collection List.

Connect the multi-reference field to a Collection List

In this example, we have a Blog Posts Collection with a multi-reference field that’s referencing the "Tags" Collection. Drop a Collection list onto the Blog Post Collection page, and connect it to the "Tags" multi-reference field.

Make sure you connect to the multi-reference field and not the actual Collection that is referenced. If you connect to the actual collection, that 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 you add an element to this Collection List, you can pull the content for that element from any of the referenced Collection’s fields. For example, you can use a tag’s name in a heading element and the tag’s icon in an image element.

Caption: In this clip, we show you how you can pull the values of a number of fields from a Contributors Collection right into a Blog Post.

Filter a Collection list using the multi-reference field

Let's say you have a Collection of "Blog posts" that has a multi-reference field connected to a "Tags" Collection. You can use the "Tags" multi-reference field to filter Collection Lists connected to the "Tags" Collection on both the "Blog posts" and "Tags" Collection pages.

Show all items that contain the current referenced field

For example, you can show all "Blog Posts" that reference a Tag on the "Tags" Collection Page. To do this:

Add a Collection List on the "Tags" Collection page and connect it to the "Blog Posts" Collection
Create the following filter rule: Tags — contains — Current Tag

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

Let's say, on the "blog posts" page, you want to display a list of all related "Blog posts" that have any of the same "Tags" as the "Blog post" you’re currently viewing. You can do as follows:

Add a Collection List on the "Blog posts" Collection page and connect it to the "Blog Posts" Collection
Create the following filter rule: Tags — contains — Any Tags of current Blog post

Set conditional visibility using the multi-reference field

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

This type of condition can only be created within a collection list that's connected to the collection that has the multi-reference field or on the collection template page of this collection. For example, if you have a collection called “Blog posts” that has a multi-reference field linked to a collection called “Authors”, you can add conditions based on the reference field “Authors” in any collection list that is connected to the “Blog posts” collection as well as on the “Blog posts” template page.

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

when the multi-reference field is set or is not set
When the multi-reference field contains or doesn’t contain a specific value

Show content when a multi-referenced field is set

Let’s say we want to add an Author’s section under each blog post on the Blog post template page. We can do that by adding a collection list and connecting it to the Authors multi-reference field.

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

Select the heading
Add a condition under the conditional visibility section in the settings panel
Select your multi-reference field, Authors (multi-reference), in the first dropdown
Choose Is set in the second dropdown
Save

Common questions

Why can't I add a reference field?

You get a limited number of references per Collection. Check out the features list to learn more.

Why isn't there filtering and sorting options for Collection lists connected to a multi-reference field?

There’s no filtering and sorting options for this Collection list because it automatically shows the referenced items for that page in the order that you've selected them within the multi-reference field.

Why can't I show multi-reference field data in a Collection list?

At the moment, you can show multi-reference field values only on a Collection page, and not within a Collection list. Support for nested Collection lists is planned. Vote for and subscribe to status updates of this feature request.

‍