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
Properties
Here is the Typescript interface for each side-edit prop:
Where SideEditPropType
is defined as follows:
and IconSets
is defined as follows:
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 object3. 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 text6. 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 validfalse
: 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:
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 ofISideEditProp
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 tooptions
.display
: Choose fromtypes.OptionsDisplay.Select
(dropdown),types.OptionsDisplay.Radio
(radio buttons), ortypes.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 controlreferences
: Name of the referencedpageType
(e.g., “category” for a product).multiple
: Set totrue
for multiple selections (many-to-many), orfalse
for single selection (one-to-many).embedValues
: Whentrue
, includes all values for the related entity in a prop named{name}_embed
. Defaults tofalse
, 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.