> ## Documentation Index
> Fetch the complete documentation index at: https://buttercms.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# References

> Guide on what ButterCMS Reference fields are, and how to use them to link to other content items like related products, author profiles, and categories

**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

![Reference field configuration](https://cdn.buttercms.com/arjAFUqQTq0K9nAzvHkA)

## Field at a glance

### Input and output

<CardGroup cols={2}>
  <Card icon="arrow-right-to-bracket" title="Input type">
    One-to-one or one-to-many links to Pages or Collections
  </Card>

  <Card icon="arrow-right-from-bracket" title="API output">
    `array` (one-to-many) or `object` (one-to-one)
  </Card>
</CardGroup>

### 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

```json theme={null}
{
  "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

```json theme={null}
{
  "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          |

<Info>
  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.
</Info>

## Working with references in your application

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    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

    ```javascript theme={null}
    // 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'
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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'
    })
    ```
  </Tab>
</Tabs>

## Best practices

### Naming references

1. **Use descriptive names**: `author` not `ref1`
2. **Indicate plurality**: `category` (one-to-one) vs `categories` (one-to-many)
3. **Match the Collection name**: If Collection is "Authors", Reference could be `author`

### Collection design for references

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

### Performance

1. **Limit referenced data**: Don't create huge Collection items
2. **Use filtering**: Query only what you need
3. **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:

<Card title="Working with references" href="../../create-content/creating-editing-content/reference-fields/working-with-reference-fields">
  How to implement common use cases, including categories (grouping/filtering), testimonials (reusable content), and related articles (linking related content).
</Card>