Organize controls in groups

In this how-to, you'll learn how to organize many sideEditProps into collapsible groups.

This is useful when a brick has more than a handful of sidebar controls. Instead of showing one long list, you can split controls into sections such as layout, colors, image, or advanced settings.

Docs reference: Sidebar controls

When groups are worth it

Groups are a good fit when:

• your brick has controls for different concerns, such as content, layout, and media
• editors do not need to see every control all the time
• some controls are advanced and should stay tucked away by default

If a brick only has 2 or 3 controls, a flat sideEditProps array is usually simpler.

sideEditProps can contain groups

Normally, sideEditProps is an array of controls.

When you want collapsible sections, it can instead contain group objects with:

• groupName: the visible label of the group
• defaultOpen: whether the group starts expanded
• show: optional conditional rendering for the whole group
• props: the controls inside that group

Example

Here is a common pattern for a hero-like brick:

import { types } from 'react-bricks/rsc'
 
Hero.schema = {
  name: 'hero',
  label: 'Hero',
  sideEditProps: [
    {
      groupName: 'Layout',
      defaultOpen: true,
      props: [
        {
          name: 'paddingY',
          label: 'Vertical Padding',
          type: types.SideEditPropType.Range,
          rangeOptions: {
            min: 0,
            max: 20,
            step: 1,
          },
        },
        {
          name: 'align',
          label: 'Text Align',
          type: types.SideEditPropType.Select,
          selectOptions: {
            display: types.OptionsDisplay.Radio,
            options: [
              { value: 'left', label: 'Left' },
              { value: 'center', label: 'Center' },
            ],
          },
        },
      ],
    },
    {
      groupName: 'Background',
      props: [
        {
          name: 'backgroundImage',
          label: 'Background Image',
          type: types.SideEditPropType.Image,
          imageOptions: {
            maxWidth: 1600,
            aspectRatio: 16 / 9,
          },
        },
        {
          name: 'overlay',
          label: 'Dark Overlay',
          type: types.SideEditPropType.Boolean,
        },
      ],
    },
  ],
}

Conditionally show an entire group

The show function also works on groups, not only on individual controls.

That is helpful when a whole section depends on one toggle:

{
  groupName: 'Background',
  show: (props) => props.useBackgroundImage,
  props: [
    {
      name: 'backgroundImage',
      label: 'Background Image',
      type: types.SideEditPropType.Image,
    },
    {
      name: 'overlay',
      label: 'Dark Overlay',
      type: types.SideEditPropType.Boolean,
    },
  ],
}

So if useBackgroundImage is false, editors do not see the whole group.

A practical naming pattern

A simple convention that works well is:

• keep defaultOpen: true only for the most frequently used group
• put rare or risky options into an Advanced group
• group by editor intent, not by developer implementation

For example, Layout, Image, and Advanced is usually clearer than Booleans, Strings, and Numbers.

Good to know

• Groups are only for sidebar organization. They do not change how props are stored.
• Each control inside props works exactly as it would in a normal flat sideEditProps array.
• You can mix common controls and advanced controls without creating a separate brick.

Related reading

• Add a sidebar control
• Validate values