Side Edit Props

Each element of the sideEditProps array may be:

Directly a SideEditProp
A Collapsible group of SideEditProps

A Side Edit Prop

A side edit prop is a prop that the user will be able modify through the right sidebar. You can specify the prop and the type of control that you want to display.

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',
  ExperimentalIconSelector = 'ICON-SELECTOR',
}

and IconSets is defined as follows:

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

Collapsible group

You can organize sidebar controls into groups, using collabsible groups.
A collapsible group is an object with this interface:

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

The groupName is the name of the label used to collapse or expand the group of sidebar controls.
A group can be set as open or closed by default (defaultOpen, false by default).
A group can be hidden depending on the value of the component props (show function which receives the props as argument).
The props are an array of ISideEditProp. See below.

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 `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 when you have an image that isn't edited visually, but in the sidebar, like a background image. The `CUSTOM` type allows you to provide your own component to edit this prop.
`component`	Optional. Required in case of `SideEditPropType.Custom` type. You can provide a custom component to edit this prop. It should be a React functional component with props `value`, `onChange`, `isValid`
`validate`	Validation function. The value is valid if the function returns `true`. If the returned value is a string, it is considered as an error message. You can use the value of this prop, or, if you need it, you may access all the props' values using the second argument (which gets an object with all the key-value props).
`show`	If this function (which receives the props, the current page and the currently logged-in user) returns `true`, this editing control is shown in the sidebar, otherwise it is not shown. It's useful to conditionally show a prop's control based on another prop (for example show the "linkPath" prop if "withLink" is true) or based on the logged-in user (for example enable the Padding controls for the designer user).
`shouldRefreshStyles`	If changing the value of this could cause the injection of new styles by a CSS-in-JS library, you should set this flag to `true`: this ensures the new styles are correctly loaded.
`helperText`	Optional text shown below the control to help the user.
`textareaOptions`	Here you can specify the `height` for the textarea field.
`imageOptions`	For props of type `SideEditPropType.Image`, you may to specify the `maxWidth` value, so that the optimization algorithm knows that the max width of the image to create is 2x this maxWidth (for retina displays) and the desired `aspectRatio` for cropping.
`rangeOptions`	For props of type `SideEditPropType.Number` and `SideEditPropType.Range`, you may to specify the `min`, `max` and `step` values to correctly display the range selector.
`selectOptions`	For a props of type `SideEditPropType.Select`, you may specify: 1. `options`: the array of options available to the user. Each option has a `value` (the value passed to the React component) and a `label` (the label shown to the user in the Sidebar). See the IOption interface. 2. `getOptions`: function to return options as defined above. It receives the brick current props as an argument. The function may return an array of options or a Promise which resolves as an array of options. Useful to have dynamic options, for example from an API call. Alternative to `options` 3. `display`: one of `SELECT` (drop down select), `RADIO` or `COLOR` (a colored circle for each color is shown). In case of Color, the value should be an object with a `color` prop, and any other prop you need returned to your component (for example a className). See OptionsDisplay
`autocompleteOptions`	For a props of type `SideEditPropType.Autocomplete`, you may specify: 1. `getOptions`: the async function receiving the search input and the brick's props and returning the array of objects with the options. 2. `getKey`: a function returning a unique key value given an option's object 3. `getLabel`: a function returning the label displayed in the dropdown menu given an option's object. It is also used to display the current selected option. 4. `renderOption`: a function returning the JSX displayed in the dropdown menu given an option's object. It overrides the `getLabel` function for the dropdown menu items (`getLabel` is still used to display the selected option) 4. `placeholder`: The input placeholder 5. `debounceTime`: time to debounce the async function in milliseconds. If not specified, a default debounce of 350ms is applied 6. `getNoOptionsMessage`: function receiving the input value that should return a message when no options are returned from the async call for the current input.
`iconSelectorOptions`	Not required. If not provided all the icon sets will be available to the user. You can specify an object with the `iconSet` key, where the value is of type IconSets
`relationshipOptions`	For a props of type `SideEditPropType.Relationship`, you may specify: 1. `label`: The label. 2. `references`: the name of the referenced `pageType` (for example, for product, it could be "category". 3. `multiple`: if `true` the interface lets you choose multiple values (many-to-many relationship), otherwise it is a simple dropdown to select one value (one-to-many relationship). 4. `embedValues`: `false` by default (you have just the ID of the related entity on the field value); if `true` you will get also all the values for the related entity in a prop which name is `{name}_embed`.

Usage example

sideEditProps: [
  {
    groupName: 'Layout',
    props: [
      {
        name: 'bg',
        label: 'Background',
        type: types.SideEditPropType.Select,
        selectOptions: {
          display: types.OptionsDisplay.Color,
          options: [
            {
              label: 'White',
              value: { color: '#fff', className: 'bg-white dark:bg-gray-900' },
            },
            {
              label: 'Light gray',
              value: {
                color: '#f7fafc',
                className: 'bg-gray-100 dark:bg-gray-800',
              },
            },
          ],
        },
      },
      {
        name: 'borderTop',
        label: 'Border Top',
        type: types.SideEditPropType.Select,
        selectOptions: {
          display: types.OptionsDisplay.Select,
          options: [
            { value: 'none', label: 'None' },
            { value: 'full', label: 'Full-width' },
            { value: 'boxed', label: 'Boxed' },
          ],
        },
      },
    ],
  },
  {
    groupName: 'Title',
    defaultOpen: true,
    props: [
      {
        name: 'size',
        label: 'Title size',
        type: types.SideEditPropType.Select,
        selectOptions: {
          display: types.OptionsDisplay.Radio,
          options: [
            { value: 'medium', label: 'Medium' },
            { value: 'large', label: 'Large' },
          ],
        },
      },
      {
        name: 'buttonExternalUrl',
        label: 'Button Link',
        type: types.SideEditPropType.Text,
        validate: (value) =>
          value && value.length > 10 && String(value).startsWith('https://'),
      },
    ],
  },
]

Custom component

You can provide your own editing component for a sideEditProp (for example, a color picker).

In that case:

the type should be CUSTOM (types.sideEditPropType.Custom)
the component should be a functional component with props:
- value (the value of the prop)
- onChange (a function with the value as argument to set the new prop value)
- isValid (true if the prop match the validation rule, false otherwise, so that you can apply a style in case of invalid status).

Side Edit Props

A Side Edit Prop​

Properties​

Collapsible group​

Properties definition​

Usage example​

Custom component​