Skip to main content

​
What is a Repeater?

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

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:

Repeater: "Features"
Feature
title (Short Text): "Fast Performance"
description (Long Text): "Lightning quick load times"
icon (Media): "https://cdn.buttercms.com/icon1.svg"
Feature
title: "Easy Integration"
description: "Works with any tech stack"
icon: "https://cdn.buttercms.com/icon2.svg"
Feature
title: "Great Support"
description: "24/7 expert assistance"
icon: "https://cdn.buttercms.com/icon3.svg"

​
Field at a glance

​
Input and output

Input type

Varies; Repeater is defined in Page schema with your choice of field types

API output

array

​
API response

Fetching Repeaters from the API

Learn more about how Repeaters are returned by the API, and how to model Repeater content in your app.

​
Field configuration options

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

​
How Repeaters differ from other content structures

  • 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
  • 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
  • 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)

​
Repeater vs. Collection

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.

​
Repeater vs. Component Picker

Use a Repeater when all items have the same structure. Use a Component Picker when you need different types of content 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.

​
Next steps

Creating Repeater fields

Step-by-step guide to adding Repeaters

Managing Repeater items

Add, edit, and reorder items

Fetching Repeater data

API examples for rendering repeaters