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

# Working with Reference fields

> Implement grouping/filtering by category, reusable content like testimonials, and linking to related content with ButterCMS reference fields.

## Implementing common use cases

Several common use cases for References include:

* Page Facets for grouping/filtering
* Reusable promotional page content
* Tables of related content

Explore the tabs below to learn how to configure your content for each of these use cases in your ButterCMS dashboard, as well as how to fetch content from the API.

<Tabs>
  <Tab title="Categories (grouping and filtering content)">
    You can use Collections as Facets (filterable properties) for your Pages. The simplest example would be to add Categories to your Pages.

    ![Category Collection example](https://cdn.buttercms.com/8REHgoI5RNmWNOYBIXqO)

    ![Category Collection example](https://cdn.buttercms.com/9NDrQf4DSaqZRxBI0Spe)

    {/* IMAGE_SOURCE: file_path="knowledge-base/content-modeling-basics/use-cases-for-buttercms-collections.md" */}

    ![Category Collection configuration](https://cdn.buttercms.com/ZzW0WwTGyWv0PpmktHTA)

    Add categories to your Collection:

    ![Adding categories](https://cdn.buttercms.com/baHte1dxRBuZpatlIi0W)

    ![Adding categories](https://cdn.buttercms.com/hltqxMqNQtiaqFLnNRFu)

    ![Adding Reference field](https://cdn.buttercms.com/Q3GGsCYeR9qHXNg3xzu3)

    ![Adding Reference field](https://cdn.buttercms.com/gmjdR00XR4qpTAAHI2DY)

    **API Response with Category:**

    ```json theme={null}
    {
      "data": {
        "slug": "martini",
        "fields": {
          "name": "Martini",
          "image": "https://cdn.buttercms.com/martini.jpg",
          "category": {
            "name": "Martini",
            "slug": "martini"
          }
        }
      }
    }
    ```

    **Filtering by Category:**

    ```text theme={null}
    GET https://api.buttercms.com/v2/content/cocktails/?fields.category.slug=martini
    ```
  </Tab>

  <Tab title="Testimonials (reusable content)">
    You can use Collections to store reusable promotional content that can be referenced by multiple pages. A common example may be customer testimonials.

    Create a Collection for testimonials with fields for name, quote, headshot, and title/company:

    {/* IMAGE_SOURCE: file_path="knowledge-base/content-modeling-basics/use-cases-for-buttercms-collections.md" */}

    ![Testimonials Collection](https://cdn.buttercms.com/6uLEDNrRGWbklxJCI6Hg)

    Add testimonials to your Collection:

    ![Adding testimonials](https://cdn.buttercms.com/yeSEDyK8QWOs9iDLFWNf)

    ![Adding testimonials](https://cdn.buttercms.com/OsScerHLSvmDI4BabaJq)

    ![Reference to testimonials](https://cdn.buttercms.com/ZbEjSmGSfeAMEQoZVZql)

    {/* IMAGE_SOURCE: file_path="knowledge-base/content-modeling-basics/use-cases-for-buttercms-collections.md" */}

    ![Selecting testimonials](https://cdn.buttercms.com/cl4eQho4S32TzRYhQ8LU)

    Select testimonials for your page:

    ![Selecting testimonials](https://cdn.buttercms.com/eriyK7JmQ2etb4p9H865)

    **API Response:**

    ```json theme={null}
    {
      "testimonials": [
        {
          "name": "Maggie Summers",
          "headshot": "https://cdn.buttercms.com/maggie.jpg",
          "title_company": "Sasquatch",
          "quote": "After several attempts at implementing an open source CMS, I found Butter. It's the best!"
        },
        {
          "name": "Drew Johnson",
          "headshot": "https://cdn.buttercms.com/drew.jpg",
          "title_company": "App Partner",
          "quote": "Wordpress was too slow. Butter is more performant. A no brainer."
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Related articles (referencing related content)">
    Let's say you've added an articles section to your website and you want to make the articles even more helpful by showing related articles. References make this very simple to achieve.

    Add a Reference field to your **Articles** page type for `Related Articles`. It will link to many articles, so it's **One-to-Many** and links back to itself.

    {/* IMAGE_SOURCE: file_path="blog-posts/butter-updates/references-powerful-content-modeling-for-any-use-case.md" */}

    ![Related articles Reference](https://cdn.buttercms.com/MrrusLlS1Oo4rSB754pm)

    Adding and removing related articles:

    ![Managing related articles](https://cdn.buttercms.com/M2bSdR7wTeeFnCUxv4Ac)

    ![Managing related articles](https://cdn.buttercms.com/zTVsEX9dRgKRiQG2KPhW)
  </Tab>
</Tabs>