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.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
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
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
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
I need to categorize or tag content, or link to an author
I need repeating groups of fields
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
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.