References

References are a powerful field type added to Pages and Collections that allow you to create links (or references) among your content. References provide the ability to link to Items from a Collection or Pages from a Page Type from a Collection or Page. You will configure your reference fields to be either “one-to-one” or “one-to-many” references:

one-to-one: reference one page or item
one-to-many: reference more than one page or item

Field at a glance

Input and output

Input type

One-to-one or one-to-many links to Pages or Collections

API output

array (one-to-many) or object (one-to-one)

API response

Varies by type, see responses below.

Field configuration options

`Option Name`	`Type`	`Function`
Help text	string	Add help text to describe usage to your team
What will this reference?	dropdown	Select content to reference (Pages or Collections)
One-to-one/one-to-many	boolean (radio)	Choose reference types

One-to-one vs. one-to-many references

One-to-one reference

Links to a single item or page. Use when content has exactly one related item. Examples:

Article → Author (each article has one author)
Product → Brand (each product has one brand)
Page → Primary Category

{
  "author": {
    "name": "Jane Smith",
    "bio": "Technical writer with 10 years experience",
    "photo": "https://cdn.buttercms.com/jane.jpg"
  }
}

One-to-many reference

Links to multiple items or pages. Use when content can have multiple related items. Examples:

Article → Tags (article can have multiple tags)
Product → Categories (product can be in multiple categories)
Page → Related Articles

{
  "tags": [
    { "name": "Tutorial", "slug": "tutorial" },
    { "name": "Beginner", "slug": "beginner" },
    { "name": "React", "slug": "react" }
  ]
}

References vs. Repeaters

Scenario	Use Reference	Use Repeater
Content reused across pages	Yes	No
Content unique to one page	No	Yes
Need to filter/query by this data	Yes	No
Data managed separately	Yes	No
Simple list of items	Maybe	Yes

Ask yourself: “Will this content be managed independently and potentially used on multiple pages?” If yes, use a Reference to a Collection. If it’s page-specific content, use a Repeater.

Working with references in your application

JavaScript
Python

const butter = require('buttercms')('your-api-key');

// Fetch page with references
const response = await butter.page.retrieve('*', 'article-page');
const article = response.data.data.fields;

// One-to-one reference
const authorName = article.author.name;
const authorPhoto = article.author.photo;

// One-to-many reference
const categories = article.categories;
categories.forEach(category => {
  console.log(category.name, category.slug);
});

// React component with references
    function ArticlePage({ article }) {
      return (
        <article>
          <h1>{article.title}</h1>

          {/* Author (one-to-one) */}
          <div className="author">
            <img src={article.author.photo} alt={article.author.name} />
            <span>By {article.author.name}</span>
          </div>

          {/* Categories (one-to-many) */}
          <div className="categories">
            {article.categories.map(cat => (
              <a key={cat.slug} href={`/category/${cat.slug}`}>
                {cat.name}
              </a>
            ))}
          </div>

          <div dangerouslySetInnerHTML={{ __html: article.body }} />

          {/* Related articles (one-to-many) */}
          <section className="related">
            <h2>Related Articles</h2>
            {article.related_articles.map(related => (
              <a key={related.slug} href={`/articles/${related.slug}`}>
                <img src={related.featured_image} alt={related.title} />
                <h3>{related.title}</h3>
              </a>
            ))}
          </section>
        </article>
      );
    }

Filtering by reference

// Get all articles in a specific category
const articles = await butter.page.list('article', {
  'fields.category.slug': 'tutorials'
});

// Get articles by a specific author
const authorArticles = await butter.page.list('article', {
  'fields.author.slug': 'jane-smith'
});

from butter_cms import ButterCMS

client = ButterCMS('your-api-key')

# Fetch page with references
response = client.pages.get('*', 'article-page')
article = response['data']['fields']

# Access one-to-one reference
author = article['author']
print(f"Author: {author['name']}")

# Access one-to-many reference
for category in article['categories']:
    print(f"Category: {category['name']} ({category['slug']})")

# Filter by reference
tutorials = client.pages.all('article', {
    'fields.category.slug': 'tutorials'
})

Best practices

Naming references

Use descriptive names: author not ref1
Indicate plurality: category (one-to-one) vs categories (one-to-many)
Match the Collection name: If Collection is “Authors”, Reference could be author

Collection design for references

Include a slug: Essential for filtering and URLs
Add display fields: Name, title, image for rendering
Keep Collections focused: One purpose per Collection
Consider the API response: What data do you need when referencing?

Performance

Limit referenced data: Don’t create huge Collection items
Use filtering: Query only what you need
Consider pagination: For large sets of referenced items

Use cases

How to use Reference fields in the ButterCMS dashboard

For common use-cases and how to implement them in the ButterCMS dashboard, see the article below:

Working with references

How to implement common use cases, including categories (grouping/filtering), testimonials (reusable content), and related articles (linking related content).

Content types

Field types overview

Simple field types

Advanced field types

Next steps

Field at a glance

Input and output

Input type

API output

API response

Field configuration options

One-to-one vs. one-to-many references

One-to-one reference

One-to-many reference

References vs. Repeaters

Working with references in your application

Filtering by reference

Best practices

Naming references

Collection design for references

Performance

Use cases

How to use Reference fields in the ButterCMS dashboard

Working with references

Content types

Field types overview

Simple field types

Advanced field types

Next steps

Documentation Index

​Field at a glance

​Input and output

Input type

API output

​API response

​Field configuration options

​One-to-one vs. one-to-many references

​One-to-one reference

​One-to-many reference

​References vs. Repeaters

​Working with references in your application

​Filtering by reference

​Best practices

​Naming references

​Collection design for references

​Performance

​Use cases

​How to use Reference fields in the ButterCMS dashboard

Working with references

Field at a glance

Input and output

API response

Field configuration options

One-to-one vs. one-to-many references

One-to-one reference

One-to-many reference

References vs. Repeaters

Working with references in your application

Filtering by reference

Best practices

Naming references

Collection design for references

Performance

Use cases

How to use Reference fields in the ButterCMS dashboard