Side Edit Props

Each element of the sideEditProps array may be:

  • Directly a SideEditProp
  • A Collapsible group of SideEditProps

Collapsible group

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.

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>
  shouldRefreshText?: boolean
  validate?: (value: any, props?: Props) => boolean | string
  show?: (props: Props) => boolean
  textareaOptions?: {
    height?: number
  }
  rangeOptions?: {
    min: number
    max: number
    step: number
  }
  selectOptions?: {
    options?: IOption[]
    getOptions?: () => IOption[] | Promise<IOption[]>
    display: OptionsDisplay
  }
  imageOptions?: {
    maxWidth: number
  }
}

Properties definition

PropertyDefinition
nameThe name of the prop passed to the component.
labelThe label displayed in the edit Sidebar.
typeOne of TEXT, NUMBER, DATE, RANGE, BOOLEAN, SELECT, IMAGE, 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.
componentOptional. Required in case of CUSTOM type. You can provide a custom component to edit this prop. It should be a React functional component with props value, onChange, isValid
shouldRefreshTextOptional. Set to true if this prop changes the way the text is displayed (for example it changes the style of a text).
validateValidation 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).
showIf this function (which receives an object with all the key-value props) returns true, this editing control is shown in the sidebar.

It's useful to conditionally show a prop's control based on another prop (for example show the "rounded" prop for an image only if the image is loaded).
textareaOptionsHere you can specify the height for the textarea field.
rangeOptionsFor props of type NUMBER and RANGE, you may to specify the min, max and step values to correctly display the range selector.
selectOptionsFor a props of type 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. 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
imageOptionsFor props of type 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).

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).