Sidebar controls

Sidebar controls offer content editors controlled flexibility by allowing them to set properties for a brick. These properties are typically used in the component’s JSX to apply CSS rules conditionally. This enables editors to modify elements like background color, title size, or padding values.

`sideEditProps`

Sidebar controls are defined in the schema’s sideEditProps property.

This property contains an array of sidebar controls. When there are many controls, it can also include an array of collapsible groups for better organization. Each group contains its own array of controls.

Each “sideEditProp” has:

A name that matches the prop set on the React component
A label for the user interface
A type that defines the type of control that the content editors will use to set the corresponding prop (e.g., select, text, range)
Optional helper text, validation rules and conditional rendering
Additional properties specific to the control type

Usage Example

MyBrick.schema = {
  ...
  sideEditProps: [
    {
      name: 'withImage',
      label: 'With Image',
      type: types.SideEditPropType.Boolean,
    },
    {
      name: 'imageSide',
      label: 'Image Side',
      type: types.SideEditPropType.Select,
      selectOptions: {
        display: types.OptionsDisplay.Radio,
        options: [
          { value: 'left', label: 'Left' },
          { value: 'right', label: 'Right' },
        ],
      },
      // Show only if `withImage` is true
      show: (props) => props.withImage
    },
    {
      name: 'url',
      label: 'Url',
      type: types.SideEditPropType.Text,
      // Validate URL
      validate: (value) => value.startsWith('https://') || 'Invalid URL'
    },
  ],
...
}

Properties

Here is the Typescript interface for each side-edit prop:

interface ISideEditProp {
  name: string
  label: string
  type: SideEditPropType
  component?: React.FC<ICustomKnobProps>
  validate?: (value: any, props?: Props) => boolean | string
  show?: (props: Props, page: Page, user: User) => boolean
  helperText?: string
  shouldRefreshStyles?: boolean
  textareaOptions?: {
    height?: number
  }
  imageOptions?: {
    maxWidth?: number
    quality?: number // default 80
    aspectRatio?: number
  }
  rangeOptions?: {
    min?: number
    max?: number
    step?: number
  }
  selectOptions?: {
    options?: IOption[]
    getOptions?: (props: Props) => IOption[] | Promise<IOption[]>
    display: OptionsDisplay
  }
  autocompleteOptions?: {
    getOptions: (input: string, props: Props) => any[] | Promise<any[]>
    getKey: (option: any) => string | number
    getLabel: (option: any) => string
    renderOption?: ({
      option,
      selected,
      focus,
    }: {
      option: any
      selected: boolean
      focus: boolean
    }) => React.ReactElement
    placeholder?: string
    debounceTime?: number
    getNoOptionsMessage?: (input?: string) => string
  }
  iconSelectorOptions?: {
    iconSets?: IconSets[]
  }
  relationshipOptions?: {
    references: string
    multiple: boolean
    label?: string
    embedValues?: boolean
  }
}

Where SideEditPropType is defined as follows:

enum SideEditPropType {
  Text = 'TEXT',
  Textarea = 'TEXTAREA',
  Number = 'NUMBER',
  Date = 'DATE',
  Range = 'RANGE',
  Boolean = 'BOOLEAN',
  Select = 'SELECT',
  Autocomplete = 'AUTOCOMPLETE',
  Image = 'IMAGE',
  Custom = 'CUSTOM',
  Relationship = 'RELATIONSHIP',
  IconSelector = 'ICON-SELECTOR',
}

and IconSets is defined as follows:

enum IconSets {
  HeroIconSolid = 'hi-solid',
  HeroIconOutline = 'hi-outline',
  FontAwesome = 'fa6',
  Feather = 'fi',
}

Properties definition

Property	Definition
`name`	The name of the prop passed to the component.
`label`	The label displayed in the edit sidebar.
`type`	One of the following:`SideEditPropType.Text`, `SideEditPropType.Number`, `SideEditPropType.Date`, `SideEditPropType.Range`, `SideEditPropType.Boolean`, `SideEditPropType.Select`, `SideEditPropType.Autocomplete`, `SideEditPropType.Image`, `SideEditPropType.Custom` (see SideEditPropType). The `IMAGE` type is useful for images edited in the sidebar, like background images. The `CUSTOM` type allows you to provide your own sidebar component.
`component`	Optional. Required for `SideEditPropType.Custom` type. Provide a custom React functional component with props `value`, `onChange`, and `isValid` to edit this prop.
`validate`	Validation function that receives the value as the first argument and all props as the second argument (object with key-value pairs). It should return `true` for valid, `false` for invalid, or a string for an invalid state with an error message.
`show`	Function that determines whether to display the editing control. It receives props, current page, and logged-in user. Useful for conditional display based on other props or user roles.
`shouldRefreshStyles`	Set totrueif changing this value could trigger new style injections by a CSS-in-JS library, ensuring correct loading of new styles.
`helperText`	Optional text diplayed below the control to guide the user.
`textareaOptions`	Specify the `height` for a textarea field.
`imageOptions`	For `SideEditPropType.Image` props, specify the `maxWidth` (the optimization algorithm uses 2x this for retina displays) and desired `aspectRatio` for cropping.
`rangeOptions`	For `SideEditPropType.Number` and `SideEditPropType.Range` props, specify the `min`, `max` and `step` values.
`selectOptions`	For `SideEditPropType.Select` props, specify: 1. `options`: Array of options with `value` (passed to the React component) and `label` (shown in the Sidebar). See the IOption interface. 2. `getOptions`: function returning options or a promise resolving to options. It receives the brick current props. Use for dynamic options, for example from API calls. Alternative to `options` 3. `display`: one of `types.OptionsDisplay.Select` (dropdown), `types.OptionsDisplay.Radio` (radio buttons), or `types.OptionsDisplay.Color` (colored circles). For colors, the value should be an object with a `color` prop, and any other needed props. See OptionsDisplay
`autocompleteOptions`	For `SideEditPropType.Autocomplete` props, specify: 1. `getOptions`: Async function receiving search input and brick props, returning an array of option objects. 2. `getKey`: Function returning a unique key for an option object 3. `getLabel`: Function returning the label for an option in the dropdown and for the selected option. 4. `renderOption`: Function returning JSX for the dropdown menu, overriding `getLabel` for the dropdown menu (`getLabel` is still used to display the selected option) 5. `placeholder`: Input placeholder text 6. `debounceTime`: debounce time for the async function in milliseconds (default: 350ms). 7. `getNoOptionsMessage`: Function receiving the input value, returning a message when no options are found.
`iconSelectorOptions`	For `SideEditPropType.IconSelector` props, optional. Specify an array of `iconSets` that should be returned in the search results, where the values are of type IconSets. If not provided, all icon sets are available.
`relationshipOptions`	For `SideEditPropType.Relationship` props, specify: 1. `label`: The label. 2. `references`: Name of the referenced `pageType` (e.g., “category” for a product). 3. `multiple`: If `true`, allows multiple selections (many-to-many); if `false`, single selection (one-to-many). 4. `embedValues`: If `true`, includes all values for the related entity in a prop named `{name}_embed`; default is `false` (only ID of related entity).

Validation

You can validate user input for each sidebar control by providing a validate function

This function receives two arguments: the control’s value and an object containing all props.

It should return one of the following:

true: The value is valid
false: The value is invalid. No error message is provided, but the control will display a red border to indicate the error.
A string: the value is invalid. The value is invalid. The string serves as an error message displayed to the user.

Preventing Saves with Validation Errors

When any brick control on the page has a validation error, a tooltip appears on the “Save” button. This tooltip informs the editor that at least one error exists.

To enhance error prevention, you can set the disableSaveIfInvalidProps property to true in the React Bricks configuration. This setting prevents saving if any errors are present on the page.

Conditional rendering of controls

You can conditionally display a sidebar control by providing a show function. This function receives props, the current page, and the logged-in user as arguments.

This feature is useful for showing controls based on other controls’ values (e.g., displaying an image side prop only when an image exists) or user properties (such as hiding a control for specific users or roles).

Collapsible groups

Sidebar controls can be organized into collapsible groups for better organization.

A collapsible group is defined by this interface:

interface ISideGroup {
  groupName: string
  defaultOpen?: boolean
  show?: (props: Props) => boolean
  props: ISideEditProp[]
}

The interface properties are:

groupName: The group’s label. Clicking it toggles the expansion of the control group.
defaultOpen: Specifies whether the group is initially expanded (defaults to false).
show: A function determining the group’s visibility based on component props.
props: An array of ISideEditProp objects defining the group’s controls.

Control types

Let’s examine each type of available control in more detail.

Simple types

Some simple types require no additional configuration. These include Text, Date, and Boolean.

Select

Use this control type when you want content editors to choose one value from multiple options.

You can present the options as a drop-down menu, a set of radio buttons, or multiple colored circles for color selection. Values can be provided statically with options or dynamically through an async function call (getOptions) that resolves to the options array.

To configure the select control, use the selectOptions object with the following properties:

options: An array of options, each with a value (passed to the React component) and a label (displayed in the Sidebar). Refer to the IOption interface for details.
getOptions: A function that returns options or a promise resolving to options. It receives the brick’s current props. Use this for dynamic options, such as those from API calls. This is an alternative to options.
display: Choose from types.OptionsDisplay.Select (dropdown), types.OptionsDisplay.Radio (radio buttons), or types.OptionsDisplay.Color (colored circles). For colors, the value should be an object with a color prop and any other necessary props. See OptionsDisplay for more information.

Autocomplete

Use this control type when you want content editors to choose one value from multiple options returned by an async function call to external APIs. The options depend on the user’s input, providing search-like functionality.

To configure the autocomplete control, use the autocompleteOptions object with the following properties:

getOptions: An async function that receives search input and brick props, returning an array of option objects.
getKey: A function returning a unique key for an option object.
getLabel: A function returning the label for an option in the dropdown and for the selected option.
renderOption: A function returning JSX for the dropdown menu items, overriding getLabel for the menu (note: getLabel is still used to display the selected option).
placeholder: The input placeholder text.
debounceTime: The debounce time for the async function in milliseconds (default: 350ms).
getNoOptionsMessage: A function receiving the input value and returning a message when no options are found for the current input.

Image

Use this control type for images that can’t be edited visually by clicking on the content, such as background images.

To configure the image control, use the imageOptions object with the following properties:

maxWidth: The optimization algorithm uses twice this width as the maximum dimension for retina displays.
aspectRatio: Sets a fixed aspect ratio for cropping (e.g. 16 / 9).

Number and Range

For Number and Range controls, you can specify rangeOptions. This object allows you to set the min (minimum), max (maximum), and step values. These parameters define the control’s range and increment.

Textarea

For Textarea controls, you can specify textareaOptions. This object has a single property, height, which allows you to set the desired height for the field.

Icon Selector

Content editors often need to choose an icon from a set, searching by keywords. The IconSelector control type is ideal for this scenario. It provides an autocomplete control that connects to our advanced icon search service, allowing semantic searches for icons from popular libraries such as HeroIcons, Feather icons, and FontAwesome.

In the iconSelectorOptions, you can specify iconSets, an array of types.IconSets that should be available in the search results. If not specified, all icon sets will be available.

The prop value is of type types.Icon. Pass it to the Icon component to render an inline SVG that allows customizing props like width, height, and className.

Relationship

Use this control when you want editors to choose a page of a specific pageType, establishing a relationship between the current brick and a page or entity.

This is particularly useful when you need to render custom field values of a related entity (for instance, the name of a product’s related category).

In the relationshipOptions, specify:

label: The label for the select control
references: Name of the referenced pageType (e.g., “category” for a product).
multiple: Set to true for multiple selections (many-to-many), or false for single selection (one-to-many).
embedValues: When true, includes all values for the related entity in a prop named {name}_embed. Defaults to false, providing only the ID of the related entity.

Custom Components

You can provide your own editing component for a sideEditProp (for example, a small map for latitude and longitude selection). In this case, set the type of control to types.sideEditPropType.Custom.

Provide your own React functional component in the component property. This component will receive the following props:

value: The current value of the prop.
onChange: A function that accepts a new value as an argument to update the prop.
isValid: A boolean indicating whether the prop matches the validation rules, allowing you to apply styles for invalid states.