Multi Select

The multiSelect control allows users to select multiple options from a list, displaying the number of selected items and the individual selections. It offers both synchronous and asynchronous loading of choices, enhancing flexibility and user experience.

Example of the multiSelect without selection:

Example of the multiSelect with single selection:

Example of the multiSelect with multiple selections:

Parameters

Name	Type	Default	Description
id	string	-	The identifier of the key where the control will save your data
type	string	-	Type should be "multiSelect" to use this control
label?	string	-	The label displayed on the left side of the control
icon?	string	-	Icon name that will be rendered on left side of the control's label. View all icons.
placeholder?	string	-	The placeholder text displayed in the multiselect field.
position?	number	-	The position of the control in toolbar
roles?	Array<Role>	-	Render the control only if the current user's role matches one of the roles in the provided array. type Role = "admin" | "viewer" | "editor" | "designer" | "manager"
devices?	"all" | "desktop" | "responsive"	"all"	Define the devices where the control will be rendered. "all" renders the control on all devices. "desktop" renders the control only on desktop devices. "responsive" renders the control on both tablet and mobile devices.
disabled?	boolean	false	Configure the condition under which the control is disabled or enabled.
display?	"inline" | "block"	"inline"	Configure how the control and its label will be arranged. If display is "inline" then label and control will be in one row, if display is "block" then label will be in one row, and the next row down will be the control.
helper?.content	string	-	If provided, an icon is displayed next to the label. When hovering over this icon, a tooltip with additional information appears.
helper?.position	"top-start" | "top" | "top-end" | "right-start" | "right" | "right-end" | "bottom-end" | "bottom" | "bottom-start" | "left-end" | "left" | "left-start"	"top"	Specifies the position of the tooltip relative to the helper icon.
states?	Array<State>	["normal"]	Allows for different styles based on the element's state State = "normal" | "hover" | "active" "normal" - the normal state of an element, "hover" - the state when the element is hovered over, "active" - the state when the element is active (e.g., current page in pagination)
choices	ChoicesSync | ChoicesAsync	-	The choices property can be configured to either synchronously or asynchronously provide a list of selectable options for a given component. This property can take two forms: ChoicesSync or ChoicesAsync. ChoicesSync ChoicesSync is an array of Choice objects that are directly provided to the component. Choice: { title: string; value: string } Each Choice object defines the following properties: title - A string representing the display title of the choice. value - A value representing the choice. This value is returned when the choice is selected. ChoicesAsync ChoicesAsync is used to load the choices dynamically via asynchronous functions. It is an object that defines the following properties: ChoicesAsync: { load: (value: Array<string>, abortSignal?: AbortSignal) => Promise<Choice[]>; search: (search: string, abortSignal?: AbortSignal) => Promise<Choice[]>; } load - A function that takes a value and optionally an AbortSignal, and returns a Promise resolving to an array of Choice objects. This function is used to load the select choices. search - A function that takes a search string from the search input and optionally an AbortSignal, and returns a Promise resolving to an array of Choice objects based on the search criteria. This function is used to dynamically search and load choices based on user input.
config?.search	boolean	-	If provided and set to true, an input field is displayed at the top to search items within the control.
config?.showArrow	boolean	-	If provided and set to true an arrow is displayed to the right.
config?.fetchOnMount	boolean	false	If provided and set to true, the load handler will be called automatically on first render. This is only applicable for async choices and is particularly useful when search is disabled, as it ensures choices are loaded and displayed immediately.
default?	Default	-	The default control value. Default: { value: Array<string> } value - the control's custom initial value
style?	function	-	This function generates CSS output based on the value from the control. The parameter is an object containing a value key, which holds the current value of the control. The function returns an object with a CSS selector key and CSS property values. style: ({value}) => { return { "{{WRAPPER}} .brz-text": { color: value.includes("events") ? "green" : "black" } } }

Basic example

Standard definition with only the required keys. This control will be displayed on all devices.

{
  id: "type",
  type: "multiSelect",
  choices: [
    { title: "Timeline", value: "timeline" },
    { title: "Events", value: "events" }
  ]
}

Return value

The return value of the multiSelect control is a stringified array of selected Choices titles.

{
  value: string;
}

Example of value:

{
  value: "['events', 'timeline']"
}

Usage

Label example

Adding a label on the left side of the control.

{
  id: "type",
  label: "Layout",
  type: "multiSelect",
  choices: [
    { title: "Timeline", value: "timeline" },
    { title: "Events", value: "events" }
  ]
}

Icon example

Adding a "star" icon to the left of the control's label.

{
  id: "type",
  type: "multiSelect",
  icon: "nc-star",
  choices: [
    { title: "Timeline", value: "timeline" },
    { title: "Events", value: "events" }
  ]
}

Roles example

Show the control only to users with admin and designer privileges.

{
  id: "type",
  type: "multiSelect",
  roles: ["admin", "designer"],
  choices: [
    { title: "Timeline", value: "timeline" },
    { title: "Events", value: "events" }
  ]
}

Placeholder example

The placeholder text displayed in the multiselect field.

{
  id: "type",
  type: "multiSelect",
  placeholder: "Select choices",
  choices: [
    { title: "Timeline", value: "timeline" },
    { title: "Events", value: "events" }
  ]
}

Devices examples

It will be rendered on all devices. This value can be skipped because it is set to "all" by default.

{
  id: "type",
  type: "multiSelect",
  devices: "all",
  choices: [
    { title: "Timeline", value: "timeline" },
    { title: "Events", value: "events" }
  ]
}

Rendering will occur only on desktop.

{
  id: "type",
  type: "multiSelect",
  devices: "desktop",
  choices: [
    { title: "Timeline", value: "timeline" },
    { title: "Events", value: "events" }
  ]
}

The display is limited to responsive modes, specifically tablet and mobile.

{
  id: "type",
  type: "multiSelect",
  devices: "responsive",
  choices: [
    { title: "Timeline", value: "timeline" },
    { title: "Events", value: "events" }
  ]
}

Disabled examples

Control will be disabled. Normally, here should be your dynamic condition.

{
  id: "type",
  type: "multiSelect",
  disabled: true,
  choices: [
    { title: "Timeline", value: "timeline" },
    { title: "Events", value: "events" }
  ]
}

Control will be disabled when videoType variable will be "custom". getValue is a getter function that allows us to retrieve the value of controls by their id. "videoType" is the id of the "select" control below.

const getToolbarContols = ({ getValue }) => {
  const videoType = getValue("videoType");

  return [
    {
      id: "videoType",
      type: "select",
      choices: [
        { title: "Youtube", value: "youtube" },
        { title: "Custom", value: "custom" }
      ]
    },
    {
      id: "type",
      type: "multiSelect",
      disabled: videoType === "custom",
      choices: [
        { title: "Timeline", value: "timeline" },
        { title: "Events", value: "events" }
      ]
    }
  ]
}

Display examples

In this example, with display: "block", the label will be rendered on the first row and the control on the second.

{
  id: "type",
  type: "multiSelect"
  display: "block",
  choices: [
    { title: "Timeline", value: "timeline" },
    { title: "Events", value: "events" }
  ]
}

Helper examples

The helper object contains a content property with the value "Helper", which will be displayed as additional guidance or information for the user.

{
  id: "type",
  type: "multiSelect",
  choices: [
    { title: "Timeline", value: "timeline" },
    { title: "Events", value: "events" }
  ],
  helper: {
    content: "Helper"
  }
}

When the helper object contains a position property with the value "top-start", it indicates that the helper text will be displayed at the top left corner of the icon.

{
  id: "type",
  type: "multiSelect",
  choices: [
    { title: "Timeline", value: "timeline" },
    { title: "Events", value: "events" }
  ],
  helper: {
    content: "Helper",
    position: "top-start"
  }
}

States example

Allows the control to work in normal and hover states.

{
  id: "type",
  type: "multiSelect", 
  states: ["normal", "hover"],
  choices: [
    { title: "Timeline", value: "timeline" },
    { title: "Events", value: "events" }
  ]
}

Allows the control to work in normal, hover and active states.

{
  id: "type",
  type: "multiSelect", 
  states: ["normal", "hover", "active"],
  choices: [
    { title: "Timeline", value: "timeline" },
    { title: "Events", value: "events" }
  ]
}

Async choices example

loadChoices: This asynchronous function fetches a list of Choice objects from a URL based. It returns an array of Choice objects. The value parameter represents the currently selected Choice within the control. This value can be used for various purposes, such as filtering results, populating other parts of the form, or programmatically interacting with the selected choice. The function additionally accepts an AbortSignal parameter, allowing the fetch operation to be cancelled if needed.

searchChoices: Similar to loadChoices, this function returns an array of Choice objects based on the search term entered in the control's input field.

const loadChoices = async (value: Value, abortSignal: AbortSignal): Promise<Choice[]> => {
  const response = await fetch(URL, { signal: abortSignal });

  return response.json();
};

const searchChoices = async (search: string, abortSignal: AbortSignal): Promise<Choice[]> => {
  const body = JSON.stringify({ searchCriteria: search });

  const response = await fetch(URL, { signal: abortSignal, body });

  return response.json();
};

{
  id: "type",
  type: "multiSelect",
  choices: {
    load: loadChoices,
    search: searchChoices
  }
}

Config fetchOnMount example

When using async choices, you can set fetchOnMount to true to automatically load choices when the component first renders. This is particularly useful when you want to display all available choices without requiring user interaction.

{
  id: "type",
  type: "multiSelect",
  choices: {
    load: loadChoices,
    search: searchChoices
  },
  config: {
    fetchOnMount: true
  }
}

Config fetchOnMount with disabled search example

When search is disabled, it's recommended to also set fetchOnMount to true. Without this configuration, no choices will be displayed at all since users cannot search to trigger the load function.

{
  id: "type",
  type: "multiSelect",
  choices: {
    load: loadChoices,
    search: searchChoices
  },
  config: {
    search: false,
    fetchOnMount: true
  }
}

Config search example

For the example below, an input field appears above the dropdown. This allows users to easily find a choice by its title.

{
  id: "type",
  type: "multiSelect",
  choices: [
    { title: "Timeline", value: "timeline" },
    { title: "Events", value: "events" }
  ],
  config: {
    search: true
  }
}

Config showArrow example

An arrow icon appears to the right of the multiSelect.

{
  id: "type",
  type: "multiSelect",
  choices: [
    { title: "Timeline", value: "timeline" },
    { title: "Events", value: "events" }
  ],
  config: {
    showArrow: true
  }
}

Default value examples

In this example, the multiSelect control that has the value "['events']" by default.

{
  id: "type", 
  type: "multiSelect",
  choices: [
    { title: "Timeline", value: "timeline" },
    { title: "Events", value: "events" }
  ],
  default: {
    value: "['events']"
  }
}

CSS examples

Change the .brz-text element color with CSS using a multiSelect control value.

{
  id: "type",
  type: "multiSelect",
  choices: [
    { title: "Timeline", value: "timeline" },
    { title: "Events", value: "events" }
  ],
  style: ({ value }) => {
    if (value.value.includes("events")) {
      return {
        "{{WRAPPER}} .brz-text": {
          "color": "orange"
        }
      }
    }

    return {
      "{{WRAPPER}} .brz-text": {
        "color": "black"
      }
    }
  }
}

Usage in HTML example

In the example below, we use the multiSelect output value to determine when to render the label in the button element. When the multiSelect includes "evenets", we will render the label. We also use the same multiSelect value to add the "data-disabled" HTML attribute to the .brz-button.

import { Brizy } from "@brizy/core";
import { Icon } from "./Icon";
import React, { JSX } from "react";

interface Props {
  type: string;
}

const Button = (props: Props): JSX.Element => {
  const { type } = props;

  const parsed = JSON.parse(type);

  const attributes = {
    "data-disabled": parsed.includes("events")
  }

  return (
    <div className="brz-button" {...attributes}>
      {parsed.includes("events") && <span>Show Events</span>}
      <Icon name="calendar"/>
    </div>
  );
};

Brizy.registerComponent({
  id: "ThirdParty.Button",
  component: { editor: Button, view: Button },
  title: "My Button",
  category: "custom",
  options: (props) => {
    return [
      {
        selector: ".brz-button",
        toolbar: [
          {
            id: "toolbarCurrentElement",
            type: "popover",
            config: {
              icon: "nc-button",
              title: "Button"
            },
            devices: "desktop",
            options: [
              {
                id: "type",
                type: "multiSelect",
                choices: [
                  { title: "Timeline", value: "timeline" },
                  { title: "Events", value: "events" }
                ],
                devices: "desktop"
              }
            ]
          }
        ]
      }
    ];
  }
});