Field Grouping

Field grouping allows you to organize related fields into collapsible groups or tabs.

Customizing field layouts

Use the renderFields API to control how fields are rendered for a component.

The function receives a fields object containing each visible field as a React node, keyed by field name. Fields appear in the order they are rendered:

const config = {
  components: {
    Heading: {
      fields: {
        title: { type: "text" },
        weight: {
          type: "radio",
          options: [
            { label: "Light", value: "light" },
            { label: "Bold", value: "bold" },
          ],
        },
        size: { type: "number" },
      },
      renderFields: ({ fields }) => (
        <>
          {fields.title}
          {fields.size}
          {fields.weight}
        </>
      ),
      // ...
    },
  },
};

Creating field groups

Use the FieldGroup component in renderFields to organize related fields under a shared label:

import { FieldGroup } from "@puckeditor/core";
 
const config = {
  components: {
    Heading: {
      fields: {
        title: { type: "text" },
        weight: {
          type: "radio",
          options: [
            { label: "Light", value: "light" },
            { label: "Bold", value: "bold" },
          ],
        },
        size: { type: "number" },
      },
      renderFields: ({ fields }) => (
        <>
          {fields.title}
          <FieldGroup label="Appearance">
            {fields.weight}
            {fields.size}
          </FieldGroup>
        </>
      ),
      // ...
    },
  },
};

Expanded by default

Field groups are collapsed by default. Set the defaultExpanded prop to true to expand them instead:

<FieldGroup label="Appearance" defaultExpanded={true}>
  {fields.weight}
  {fields.size}
</FieldGroup>

Non-collapsible field groups

To disable group collapsing and persist the fields, set the collapsible prop to false:

<FieldGroup label="Appearance" collapsible={false}>
  {fields.weight}
  {fields.size}
</FieldGroup>

Creating field tabs

Use the FieldTab component in renderFields to organize fields into tabs:

import { FieldTab } from "@puckeditor/core";
 
const config = {
  components: {
    Heading: {
      fields: {
        title: { type: "text" },
        weight: {
          type: "radio",
          options: [
            { label: "Light", value: "light" },
            { label: "Bold", value: "bold" },
          ],
        },
        size: { type: "number", min: 16, max: 64 },
      },
      renderFields: ({ fields }) => (
        <>
          <FieldTab label="Content">{fields.title}</FieldTab>
          <FieldTab label="Appearance">
            {fields.weight}
            {fields.size}
          </FieldTab>
        </>
      ),
      // ...
    },
  },
};

Tabs appear in the order they are rendered.

You can also use FieldGroup inside a FieldTab to group related fields within a tab:

<FieldTab label="Appearance">
  <FieldGroup label="Typography">
    {fields.weight}
    {fields.size}
  </FieldGroup>
</FieldTab>