Skip to main content

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

PropertyDefinition
nameThe name of the prop passed to the component.
labelThe label displayed in the edit Sidebar.
typeOne 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.
componentOptional. 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
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 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).
shouldRefreshStylesIf 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.
helperTextOptional text shown below the control to help the user.
textareaOptionsHere you can specify the height for the textarea field.
imageOptionsFor 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.
rangeOptionsFor props of type SideEditPropType.Number and SideEditPropType.Range, you may to specify the min, max and step values to correctly display the range selector.
selectOptionsFor 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
autocompleteOptionsFor 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.
iconSelectorOptionsNot 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
relationshipOptionsFor 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).