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.
Option NameTypeFunction
Required?booleanMake field required to save Page
Help textstringAdd help text to describe usage to your team
Min # of itemsnumberSet a minimum number of items in Repeater
Max # of itemnumberSet a maximum number of items in Repeater

​
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.
RepeaterCollection
Content tied to a specific Page or Page TypeShared, reusable data across Page Types
Create inline while editingCreate separately, then reference
Best for Page-specific listsBest for global data like categories
No separate management viewManaged in a dedicated Collections section

​
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.
RepeaterComponent Picker
Same fields repeatedDifferent field sets per item
Consistent structureFlexible structure
Best for listsBest for Page sections
e.g., FAQs, Team memberse.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.

​
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