Fields overview

Overview of all ButterCMS field types — the data they accept, which content types support them, and basic use cases for each field.

The following article discusses the different field types, the content types they can be used with, and how to choose between them. For more information on configuring and working with fields, you can also see the following articles:

Configuring and validating fields

How to configure and validate fields, including adding custom validation rules to ensure data integrity in ButterCMS

Adding default values to fields

How to add default values, including common use-cases, examples, and best practices.

Simple and advanced field types

ButterCMS provides a variety of different field types to allow you to build flexible schemas for your Pages and Collections.

Simple field types allow you to restrict data to a specific type, such as short and long text fields, number fields, checkbox fields, media fields, and more.

ButterCMS also has five advanced field types that allow you to structure more complex data: references, repeaters, components, component pickers, and form integration fields.

Select any field type in the left menu to get more information on that field, including: input types, API response examples, field configuration options, common use cases, best practices, and more.

Quick reference table

Here is an at-a-glance reference to the content fields available in ButterCMS, their API response output type, and some examples of use cases.

Content fields available in ButterCMS

Field type	Output type	Primary use case
Short Text	string	Titles, headlines, labels, URLs
Long Text	string	Descriptions, excerpts, markdown content
WYSIWYG	string (HTML)	Rich formatted content, blog posts
HTML	string (HTML)	Custom code, embed snippets
Number	number	Prices, quantities, dimensions
Date	string (ISO)	Publish dates, event times
Dropdown	string	Status selection, predefined choices
Checkbox	boolean	Feature flags, visibility toggles
Color	string (hex)	Brand colors, theme customization
Media	string (URL) unless alt_text parameter provided	Images, documents, files
Reference	object/array	Categories, authors, related content
Component	object	Fixed structured blocks
Component Picker	array	Dynamic page sections
Repeater	array	Lists, carousels, repeated data
Form integrations	Depends on form provider	See Form Integration Fields.

Pages vs. Collections: field availability

Not all field types are available in both Pages and Collections:

Feature	Pages	Collections
Basic Fields (Text, Number, Date, etc.)	✅	✅
Media Fields	✅	✅
Reference Fields	✅	✅
Component	✅	❌
Component Picker	✅	❌
Repeater	✅	❌
Form integration fields	✅	❌

Choosing the right field type

I need a simple title or label

Use Short Text. Configure max length if you need to limit characters for design consistency.

I need formatted or rich content like a blog post

Use WYSIWYG for rich text editing. You can customize the toolbar to control which formatting options are available.

I need to add images

Use Media for single images. For galleries, use a Repeater with Media fields inside. Alt text is supported. You can also insert images from your Media Library directly into a WYSIWYG field.

I need to categorize or tag content, or link to an author

Create a Collection (e.g., Categories) and use a Reference field to link it. This allows filtering and reuse.

I need repeating groups of fields

Use a Repeater if the content is unique to one page. Use a Reference to a Collection if you need to reuse the content across multiple pages.

I need flexible page sections that editors can reorder

Use a Component Picker to let editors choose from multiple component types and arrange them in any order.