Preview

Note: Options are set via the options JavaScript property. See usage below.

Usage

<cs-multiselect placeholder="Choose options"></cs-multiselect>

<script>
  const multiselect = document.querySelector('cs-multiselect');
  multiselect.options = [
    { label: 'Option 1', value: '1' },
    { label: 'Option 2', value: '2' },
    { label: 'Option 3', value: '3' },
  ];
  multiselect.selectedOptions = [
    { label: 'Option 1', value: '1' },
  ];
</script>

Properties

aria-labelstring default: null

Adds aria-label to the select element. Use this if you don't have a visible label for this control.

aria-requiredboolean

Adds aria-required to the native input element.

auto-focusboolean

Automatically focuses the trigger when component is mounted.

control-idstring

Specifies the ID for the trigger component. It uses an automatically generated ID by default.

deselect-aria-labelMultiselectProps.DeselectAriaLabelFunction

Specifies an aria-label for the token deselection button.

disabledboolean

Determines whether the whole select component is disabled.

enable-select-allboolean

Enables users to select and deselect all options with a special extra checkbox which is displayed at the start of the dropdown.

expand-to-viewportboolean

By default, the dropdown height is constrained to fit inside the height of its next scrollable container element. Enabling this property will allow the dropdown to extend beyond that container by using fixed positioning and React Portals.

Set this property if the dropdown would otherwise be constrained by a scrollable container, for example inside table and split view layouts.

We recommend you use discretion, and don't enable this property unless necessary because fixed positioning results in a slight, visible lag when scrolling complex pages.

filtering-aria-labelstring

Adds an aria-label on the built-in filtering input if filtering is enabled.

filtering-clear-aria-labelstring

Adds an aria-label to the clear button inside the search input.

filtering-placeholderstring default: ''

Specifies the placeholder to display in the filtering input if filtering is enabled.

filtering-results-text(matchesCount: number, totalCount: number) => string

Specifies the text to display with the number of matches at the bottom of the dropdown menu while filtering.

filtering-typeOptionsFilteringType default: 'none'

Determines how filtering is applied to the list of options:

• auto - The component will automatically filter options based on user input.
• manual - You will set up onChange or onLoadItems event listeners and filter options on your side or request them from server.

By default the component will filter the provided options based on the value of the filtering input field. Only options that have a value, label, description or labelTag that contains the input value as a substring are displayed in the list of options.

If you set this property to manual, this default filtering mechanism is disabled and all provided options are displayed in the dropdown list. In that case make sure that you use the onChange or onLoadItems events in order to set the options property to the options that are relevant for the user, given the filtering input value.

Note: Manual filtering doesn't disable match highlighting.

hide-tokensboolean default: false

Hides the tokens displayed underneath the component. Only use this if the selected options are displayed elsewhere on the page.

i18n-stringsMultiselectProps.I18nStrings

An object containing all the localized strings required by the component.

• selectAllText (string) - Specifies the text to be displayed next to the checkbox that selects or deselects all options.
• tokenLimitShowFewer (string) - Specifies the text to be displayed in the "Show fewer" button for the token group control.
• tokenLimitShowMore (string) - Specifies the text to be displayed in the "Show more" button for the token group control. This string should not contain the number of hidden tokens because this will be added by the component automatically.

inline-label-textstring

Specifies an inline label that appears next to the multiselect trigger.

inline-tokensboolean

Shows tokens inside the trigger instead of below it.

keep-openboolean default: false

Determines whether the dropdown list stays open after the user selects an item.

namestring

optionsSelectProps.Options default: []

Specifies an array of options that are displayed to the user as a dropdown list. The options can be grouped using OptionGroup objects.

Option

• value (string) - The returned value of the option when selected.

OptionGroup

• value (string) - Used to locate option group in test utils.
• options (Option[]) - (Optional) The options under this group.

Shared Option and OptionGroup properties

• label (string) - (Optional) Option or group text displayed to the user.
• lang (string) - (Optional) The language of the option or group, provided as a BCP 47 language tag.
• description (string) - (Optional) Further information about the option or group that appears below the label.
• disabled (boolean) - (Optional) Determines whether the option or group is disabled.
• disabledReason (string) - (Optional) Displays tooltip near the item when disabled. Use to provide additional context.
• labelTag (string) - (Optional) A label tag that provides additional guidance, shown next to the label.
• tags [string[]] - (Optional) A list of tags giving further guidance about the option or group.
• filteringTags [string[]] - (Optional) A list of additional tags used for automatic filtering.
• iconName (string) - (Optional) Specifies the name of an icon to display in the option or group.
• iconAriaLabel (string) - (Optional) Specifies alternate text for the icon. We recommend that you provide this for accessibility.
• iconAlt (string) - (Optional) Deprecated, replaced by `iconAriaLabel`. Specifies alternate text for a custom icon, for use with iconUrl.
• iconUrl (string) - (Optional) URL of a custom icon.
• iconSvg (unknown) - (Optional) Custom SVG icon. Equivalent to the svg slot of the icon component.

Note: Only one level of option nesting is supported.

If you want to use the built-in filtering capabilities of this component, provide a list of all valid options here and they will be automatically filtered based on the user's filtering input.

Alternatively, you can listen to the onChange or onLoadItems event and set new options on your own.

placeholderstring default: ''

Specifies the hint text that's displayed in the field when no option has been selected.

read-onlyboolean

Specifies if the control is read-only, which prevents the user from both modifying the value and opening the dropdown. A read-only control is still focusable.

render-highlighted-aria-liveSelectProps.ContainingOptionAndGroupString

Overrides the element that is announced to screen readers when the highlighted option changes. By default, this announces the option's name and properties, and its selected state if the selectedAriaLabel property is defined. The highlighted option is provided, and its group (if groups are used and it differs from the group of the previously highlighted option).

For more information, see the accessibility guidelines.

render-optionMultiselectProps.MultiselectOptionItemRenderer

Specifies a render function to render custom options in the dropdown menu.

selected-aria-labelstring

Specifies the localized string that describes an option as being selected. This is required to provide a good screen reader experience. For more information, see the accessibility guidelines.

selected-optionsReadonlyArray<MultiselectProps.Option>required

Specifies the currently selected options. Provide an empty array to clear the selection.

token-limitnumber

Specifies the maximum number of displayed tokens. If the property isn't set, all of the tokens are displayed.

token-limit-show-fewer-aria-labelstring

Adds an aria-label to the "Show fewer" button for the token group control. Use to assign unique labels when there are multiple token groups with the same tokenLimitShowFewer label on one page.

token-limit-show-more-aria-labelstring

Adds an aria-label to the "Show more" button for the token group control. Use to assign unique labels when there are multiple token groups with the same tokenLimitShowMore label on one page.

virtual-scrollboolean

If you have more than 500 options, enable this flag to apply a performance optimization that makes the filtering experience smoother. We don't recommend enabling the feature if you have less than 500 options, because the improvements to performance are offset by a visible scrolling lag.

When you set this flag to true, it removes options that are not currently in view from the DOM. If your test accesses such options, you need to first scroll the options container to the correct offset, before performing any operations on them. Use the element returned by the findOptionsContainer test utility for this.

Slots

noMatch

Displayed for filteringType="auto" when there are no matches for the filtering.

Events

blurCustomEvent<void>

Called when input focus is removed from the UI control.

changeCustomEvent<MultiselectProps.MultiselectChangeDetail>

Called when the user selects or deselects an option. The event detail contains the current selectedOptions.

focusCustomEvent<void>

Called when input focus is set onto the UI control.

loadItemsCustomEvent<OptionsLoadItemsDetail>

Use this event to implement the asynchronous behavior for the component.

The event is called in the following situations:

• The user scrolls to the end of the list of options, if statusType is set to pending.
• The user clicks on the recovery button in the error state.
• The user types inside the input field.
• The user focuses the input field.

The detail object contains the following properties:

• filteringText - The value that you need to use to fetch options.
• firstPage - Indicates that you should fetch the first page of options that match the filteringText.
• samePage - Indicates that you should fetch the same page that you have previously fetched (for example, when the user clicks on the recovery button).