> ## Documentation Index
> Fetch the complete documentation index at: https://buttercms.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Components: key concepts

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

<Info>
  Components are only available for Pages. They are not supported by Collections or Blog Posts.
</Info>

## 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

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

## 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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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.

```json theme={null}
{
  "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

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Pages — key concepts" icon="file" href="./pages-key-concepts">
    Publication states, references, and localization for Pages
  </Card>

  <Card title="Write API — Pages" icon="pen" href="../../api-reference/pages/create-page-via-write-api">
    Create and update pages with component data
  </Card>
</CardGroup>