Build an editor with groups and sections

Design the screen the store owner uses to enter website content. A good editor follows their tasks: update the opening headline, change a service, or fix the phone number. It should not require them to understand your component names.

This guide builds the editor for the Studio example. It configures the existing dashboard; you are not writing a new React form or changing the public page layout.

1. Decide what the owner should edit

Start with a small content plan:

Owner task	Content field	Editor location
Change the main headline, introduction and image	hero group	Home page → Opening section
Show/hide the service area and edit its cards	showServices + services list	Home page → What we offer
Change the business name or phone number	business group	Shared content → Business details

Use labels that make sense to the owner. “Opening section” is easier to recognize than an internal component name such as “HeroBlockV2”. Keep fields used together in the same section.

2. Define the values before arranging the screen

Add this field to definition.json.fields and give it matching defaults. This is a fragment of the full definition, not a standalone file:

Field inside definition.json

{
  "id": "hero",
  "label": "Opening section",
  "type": "group",
  "required": true,
  "fields": [
    {
      "id": "title",
      "label": "Main headline",
      "type": "text",
      "required": true,
      "maxLength": 120
    },
    {
      "id": "summary",
      "label": "Short introduction",
      "type": "text",
      "maxLength": 600
    },
    {
      "id": "image",
      "label": "Cover image",
      "type": "asset"
    }
  ]
}

A schema group creates a nested object: content.hero.title. That is a data decision. An editor group is a navigation heading, and an editor section places existing top-level fields together. Those are interface decisions.

You can place several top-level scalar fields in one editor section without changing their data shape. Use a schema group when the values themselves should belong together as an object; do not rename saved fields simply to rearrange the screen.

3. Put the field in a named section

Create editor.json:

First editor section

{
  "contractVersion": 1,
  "groups": [
    {
      "id": "homepage",
      "label": "Home page",
      "sections": [
        {
          "id": "opening",
          "label": "Opening section",
          "fields": [
            "hero"
          ]
        }
      ]
    }
  ]
}

This produces navigation under Home page, with an Opening section containing the nested hero fields. The owner sees the definition’s labels: Main headline, Short introduction, and Cover image.

The short headline is a one-line input. The introduction uses a textarea because its maxLength is greater than 350. The cover image uses the asset picker. The schema chooses those controls; the section only arranges them.

4. Add the rest of the screen

Use the complete editor.json example to add What we offer and Shared content. Its navigation and content are:

Home page
  Opening section
    hero → Main headline, Short introduction, Cover image
  What we offer
    showServices → Show services
    services → repeatable service cards
Shared content
  Business details
    business → Business name, Phone number

The outer group array, its section arrays and each section’s fields array set the display order. Give groups and sections stable, unique IDs. These IDs are separate from field IDs.

Section references accept top-level IDs such as hero, not nested paths like hero.title. The whole schema group is rendered together. Referencing the same top-level field in two configured sections is invalid.

5. Make repeatable cards recognizable

A list of six anonymous “Item” rows is difficult to edit. Configure collection summaries so service cards show their title, description and image. The summary points to values inside each item; it does not add new fields.

6. Check the owner’s experience

1. Run shoplifter types, shoplifter validate, and build/output validation.
2. Inspect local fixtures to check how content values affect the public page.
3. Upload and stage an authorized review candidate to inspect the actual dashboard editor. npm run dev previews the site, not the dashboard editing screen.
4. Walk through each owner task: find the section, edit a value, add/reorder a service, choose an image, and check required-field feedback.
5. Review without changing the live site; follow the preview-only publication workflow.

Do not hide fields by leaving them out: unassigned fields receive automatic sections. A checkbox like showServices does not automatically hide other inputs or public markup. Your Astro component must use that value to decide whether to render the service area.

Current editor configuration supports groups, sections and collection summaries. It does not expose arbitrary columns, custom widgets, conditional visibility, per-field help text or translation maps. Project labels are displayed as written; choose the owner’s language for labels. The platform manages the dashboard’s own translated controls.