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

# Understanding Repeaters

> Repeaters let you define a group of fields that repeat multiple times within a Page—perfect for lists, galleries, carousels, and dynamic content sections.

## What is a Repeater?

{/* /SOURCE */}

A Repeater is a special field type with a two-step process:

1. Define a group of fields to be used in the repeater.
2. Content editors then add as many instances of the field as they need.

Each instance contains the same set of fields—in other words, the same structure. It's easy to add, edit, or remove instances at any time.

Repeaters are a powerful way to create structured, repeatable content like image carousels, feature lists, testimonials, and more.

### Representation of Repeater data

<Tip>
  Imagine a **Features** Repeater field, which has a Short Text field called **title**, a Long Text field called **description**, and a Media field called **icon**. If we added three instances to the Repeater, the data might look something like this:
</Tip>

<Card>
  <Tree>
    <Tree.Folder name="Repeater: &#x22;Features&#x22;" defaultOpen>
      <Tree.Folder name="Feature" defaultOpen>
        <Tree.File name="title (Short Text): &#x22;Fast Performance&#x22;" />

        <Tree.File name="description (Long Text): &#x22;Lightning quick load times&#x22;" />

        <Tree.File name="icon (Media): &#x22;https://cdn.buttercms.com/icon1.svg&#x22;" />
      </Tree.Folder>

      <Tree.Folder name="Feature" defaultOpen>
        <Tree.File name="title: &#x22;Easy Integration&#x22;" />

        <Tree.File name="description: &#x22;Works with any tech stack&#x22;" />

        <Tree.File name="icon: &#x22;https://cdn.buttercms.com/icon2.svg&#x22;" />
      </Tree.Folder>

      <Tree.Folder name="Feature" defaultOpen>
        <Tree.File name="title: &#x22;Great Support&#x22;" />

        <Tree.File name="description: &#x22;24/7 expert assistance&#x22;" />

        <Tree.File name="icon: &#x22;https://cdn.buttercms.com/icon3.svg&#x22;" />
      </Tree.Folder>
    </Tree.Folder>
  </Tree>
</Card>

## Field at a glance

### Input and output

<CardGroup cols={2}>
  <Card title="Input type" icon="arrow-right-to-bracket">
    Varies; Repeater is defined in Page schema with your choice of field types
  </Card>

  <Card title="API output" icon="arrow-right-from-bracket">
    `array`
  </Card>
</CardGroup>

### API response

<Card title="Fetching Repeaters from the API" icon="code" href="../../../build-your-app/rendering-complex-field-types/fetching-repeater-data">
  Learn more about how Repeaters are returned by the API, and how to model Repeater content in your app.
</Card>

### Field configuration options

<Tip>
  Each field you set up in the Repeater will have the configuration/validation options available to its specific field type.
</Tip>

| `Option Name`  | `Type`  | `Function`                                   |   |
| -------------- | ------- | -------------------------------------------- | - |
| Required?      | boolean | Make field required to save Page             |   |
| Help text      | string  | Add help text to describe usage to your team |   |
| Min # of items | number  | Set a minimum number of items in Repeater    |   |
| Max # of item  | number  | Set a maximum number of items in Repeater    |   |

## How Repeaters differ from other content structures

<AccordionGroup>
  <Accordion title="Use a Repeater when...">
    * Content is unique to a specific Page
    * All items share the same structure
    * You need flexible ordering and quantity
    * Examples: Page-specific FAQs, image galleries, feature lists
  </Accordion>

  <Accordion title="Use a Collection instead when...">
    * Content needs to be shared across multiple Pages
    * You need centralized management of the data
    * Items will be referenced in multiple places
    * Examples: team members, categories, shared testimonials
  </Accordion>

  <Accordion title="Use a Component Picker instead when...">
    * Each item can have different structures
    * You need mixed content types in one area
    * Building flexible page layouts
    * Examples: landing page sections (hero, CTA, features blocks)
  </Accordion>
</AccordionGroup>

### Repeater vs. Collection

<Note>
  The key question is: "Will this content be reused across multiple Pages or Page Types?" If yes, use a Reference to a Collection. If it's unique to this Page or Page Type, use a Repeater.
</Note>

| Repeater                                     | Collection                                 |
| -------------------------------------------- | ------------------------------------------ |
| Content tied to a specific Page or Page Type | Shared, reusable data across Page Types    |
| Create inline while editing                  | Create separately, then reference          |
| Best for Page-specific lists                 | Best for global data like categories       |
| No separate management view                  | Managed in a dedicated Collections section |

### Repeater vs. Component Picker

<Tip>
  Use a **Repeater** when all items have the same structure. Use a **Component Picker** when you need different types of content blocks.
</Tip>

| Repeater                 | Component Picker                 |
| ------------------------ | -------------------------------- |
| Same fields repeated     | Different field sets per item    |
| Consistent structure     | Flexible structure               |
| Best for lists           | Best for Page sections           |
| e.g., FAQs, Team members | e.g., Hero, CTA, Features blocks |

## How-tos and use cases

For common Repeater use cases and their step-by-step implementations, please refer to the [Creating repeater fields article](./creating-repeater-fields#common-use-cases).

## Next steps

<CardGroup cols={2}>
  <Card title="Creating Repeater fields" icon="plus" href="./creating-repeater-fields">
    Step-by-step guide to adding Repeaters
  </Card>

  <Card title="Managing Repeater items" icon="list-check" href="./managing-repeater-items">
    Add, edit, and reorder items
  </Card>

  <Card title="Fetching Repeater data" icon="code" href="../../../build-your-app/rendering-complex-field-types/fetching-repeater-data">
    API examples for rendering repeaters
  </Card>
</CardGroup>