Components: key concepts

How to work with the ButterCMS component system, exclusively available for Pages, to create dynamic structured layouts with reusable content blocks.

Components are only available for Pages. They are not supported by Collections or Blog Posts.

Overview

Components provide a structured approach to building dynamic page layouts with reusable, predefined content blocks. Developers define component schemas in the dashboard; content creators then populate them with data via the dashboard or Write API.

Workflow:

1. Developer phase: Define component schemas in the ButterCMS dashboard with specific field types and structures
2. Content phase: Content creators populate component fields via the dashboard or Write API
3. Delivery phase: API responses include structured component data for rendering in your application

Component schemas must be predefined in your ButterCMS dashboard before use. Components cannot be created or modified through the Write API.

Individual components

Single, structured content blocks within a page schema. Individual components maintain consistent field structures while allowing dynamic content updates.

API representation — fields are organized as a nested JSON object:

{
  "hero": {
    "image": "https://example.com/hero-image.jpg",
    "alt_text": "Hero section background image",
    "headline": "Welcome to Our Platform",
    "subtitle": "Powerful content management made simple",
    "cta_button": {
      "text": "Get Started",
      "url": "/signup"
    }
  }
}

PATCH update behavior: Individual component fields support selective updates. You only need to include the fields you want to change:

{
  "fields": {
    "hero": {
      "headline": "Updated Welcome Message"
    }
  }
}

In this example, image, alt_text, subtitle, and cta_button retain their existing values.

Common use cases: Hero sections, contact information blocks, feature highlights, testimonials.

Component picker fields

Component picker fields combine multiple predefined components in an ordered array, enabling dynamic page layouts with mixed content types.

API representation — each element identifies its type by key:

{
  "sections": [
    {
      "faq_item": {
        "question": "Are dogs allowed in the facility?",
        "answer": "Leashed dogs are welcome in all common areas.",
        "category": "Pets"
      }
    },
    {
      "trivia_block": {
        "title": "Did You Know?",
        "facts": ["Our facility was built in 1892", "We've hosted over 10,000 events"],
        "background_color": "blue"
      }
    },
    {
      "image_gallery": {
        "title": "Recent Photos",
        "images": [
          { "url": "https://example.com/photo1.jpg", "caption": "Summer event 2024" }
        ]
      }
    }
  ]
}

Update limitation: Component picker fields require complete array replacement when updating. You cannot partially update a single component within a picker — you must provide the entire array with all components and their complete field data.

{
  "fields": {
    "sections": [
      {
        "faq_item": {
          "question": "Updated question",
          "answer": "Updated answer",
          "category": "Updated Category"
        }
      }
    ]
  }
}

Ordering: The array order determines display sequence. Reorder components by changing their position in the array.

Common use cases: Landing pages, resource pages, event pages, product pages with flexible section layouts.

Media integration

When a component field is configured with a Media field type, any URL provided as the value triggers automatic media processing:

1. Remote URL is downloaded
2. Image is uploaded to your ButterCMS media library
3. CDN URL replaces the original URL in the response

{
  "hero_section": {
    "background_image": "https://external-site.com/image.jpg",
    "logo": "https://company-assets.com/logo.png"
  }
}

After processing, the external URLs are replaced with ButterCMS CDN URLs, providing optimized delivery and eliminating external dependencies.

Design guidelines

Concern	Guidance
Schema design	Design for reusability; consider common use cases before finalizing field types
Field validation	Use ButterCMS field validation to ensure data quality across component instances
Naming	Use clear, descriptive names for component types and fields
Granularity	Avoid overly complex components (impacts response times) and overly simple ones (increases API calls)
Content creator UX	Order and group fields to create intuitive editing workflows in the dashboard

Next steps

Pages — key concepts

Publication states, references, and localization for Pages

Write API — Pages

Create and update pages with component data