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

# Creating Repeater fields

> Step-by-step guide on adding a Repeater field to a content type in ButterCMS.

<Tip>
  Ready to render repeaters in your app? See [Fetching Repeater Data via API](../../../build-your-app/rendering-complex-field-types/fetching-repeater-data).
</Tip>

## Supported field types

Repeaters can contain any combination of [**simple field types**](../../../core-concepts/field-types/field-basics), including **Reference Fields** to other content types.

They cannot contain **Components**, **Component Pickers**, or other **Repeaters**.

## Step-by-step: Creating a new Page with a Repeater

<Steps>
  <Step title="Create a new Page Type">
    First, go to your Pages dashboard, click the **New Page** button and a drop-down menu will appear. Choose **Create new page**.

    ![Create new page in ButterCMS](https://cdn.buttercms.com/xNNt5He2R2O6MWB1Z54b)
  </Step>

  <Step title="Add the Repeater field">
    To create an image carousel or any repeating content, use the special field called a **Repeater**. This tool repeats the same set of fields over and over again.

    In the field selection panel on the right, find and select the **Repeater** field type. Give it a descriptive name like "image\_carousel" or "features".
  </Step>

  <Step title="Add nested fields to the Repeater">
    Add the fields that will be repeated for each item. For an image carousel example, add:

    * **Short Text** for title
    * **Short Text** for caption
    * **Media** for the actual image

    ![Repeater field with nested fields configured](https://cdn.buttercms.com/WWANGqFQFeF1nWYOHaq7)
  </Step>

  <Step title="Save the Page Type">
    Save your page with a descriptive name and API slug. The API slug will be used when fetching this page via the API.
  </Step>
</Steps>

# Common use cases

### Product image carousels

In a **Product Detail** Page Type, you can define **Product Image** as a field that uses a **Repeater**. The field has three subsequent fields nested within it — a media field and two number fields for width and height dimensions.

<Tip>
  Width and height dimensions are important for SEO and web performance speed.
</Tip>

![Repeater field in Product Detail Page Type for product images](https://cdn.buttercms.com/XVh1NveTTyuNPMxLTcCG)

Here is an example from a product detail page with multiple product images:

![Screenshot of product images attached to Product Image field](https://cdn.buttercms.com/lHXVmfrQai6ERB6tJEgO)

For this example, two images of the product were added, but you can always add more images. For developers, this field returns as an array, or list, of the product images. A developer can map over that list and render the images in any way they want.

![Gif example of product image carousel](https://cdn.buttercms.com/YrAb7pF5T1CPV6jA3Tco)

### Feature lists

To create a features section, use a Repeater field. With a Repeater, you can create a list containing a set of identical objects.

For a features section, add the following fields to the Repeater:

* **Short Text** named "Headline"
* **Long Text** named "Description"

![Features repeater configuration](https://cdn.buttercms.com/zrunyYG9TYCu5ymPUQ2c)

### Creating a Repeater inside a component

For components that need repeating content, use a Repeater field within the component. Here's how to create a services component with a Repeater:

![Services component with repeater configuration](https://cdn.buttercms.com/P2aMr7sMQ2WMDLvwruHh)

Using a Repeater field allows you to repeat the services content as many times as needed:

* **Short Text** for the service name
* **Short Text** for service tagline
* **Long Text** for service description
* **Media** for service image

<Warning>
  Repeaters cannot be placed inside Collections. They are only available in Pages and Page Types.
</Warning>

## More use cases

| Use case           | Fields                            |
| ------------------ | --------------------------------- |
| **Image carousel** | image, caption, alt\_text, link   |
| **Photo gallery**  | image, title, description         |
| **Logo wall**      | logo, company\_name, website\_url |
| **Team members**   | photo, name, title, bio, LinkedIn |

**Features & benefits**

| Use case          | Fields                                    |
| ----------------- | ----------------------------------------- |
| **Feature list**  | icon, title, description                  |
| **Pricing tiers** | name, price, features (text), cta\_button |
| **Benefits**      | icon, headline, body\_text                |
| **Stats/Metrics** | number, label, description                |

**Content lists**

| Use case                | Fields                                  |
| ----------------------- | --------------------------------------- |
| **FAQ items**           | question, answer                        |
| **Steps/Instructions**  | step\_number, title, description, image |
| **Timeline events**     | date, title, description                |
| **Resources/Downloads** | title, description, file, file\_type    |

**Social & testimonials**

| Use case         | Fields                                |
| ---------------- | ------------------------------------- |
| **Testimonials** | quote, author, company, photo, rating |
| **Social links** | platform, url, icon                   |
| **Awards**       | image, title, year, description       |

## Configuring field validation

<Note>
  See [Understanding repeaters](./understanding-repeaters#field-configuration-options) for the configuration and validation options available to the entire Repeater field. To see the configuration and validation options available to the fields nested within the Repeater, see [Configuring and validating fields](../fields-basics/configuring-and-validating-fields).
</Note>

## Best practices for repeaters

**Naming**

1. **Use plural names**: `features` not `feature`, `testimonials` not `testimonial`
2. **Be descriptive**: `product_features` if you have multiple feature repeaters
3. **Consistent field names within**: Use the same naming conventions for subfields

**Structure**

1. **Keep Repeaters focused**: 3-6 fields per Repeater is ideal
2. **Consider field order**: Put required/primary fields first
3. **Add help text**: Guide editors on what content is expected

**Performance**

1. **Keep structure flat**: Repeaters are single-level in this codebase
2. **Consider pagination**: For long lists, implement pagination in your frontend
3. **Lazy load media**: For image-heavy Repeaters, use lazy loading

**Benefits summary**

* **Content editor freedom**: Editors can add, remove, and reorder items without developer involvement
* **Consistent structure**: Every item follows the same schema, ensuring data consistency
* **Flexible output**: Developers receive clean JSON arrays to render however they choose
* **No backend changes**: Add new items without modifying code or database schemas