Preview

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

Usage

<cs-select placeholder="Choose an option"></cs-select>

<script>
  const select = document.querySelector('cs-select');
  select.options = [
    { label: 'Option 1', value: '1' },
    { label: 'Option 2', value: '2' },
    { label: 'Option 3', value: '3', disabled: true },
  ];
  select.selectedOption = { 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-labelledbystring default: null

Adds aria-labelledby to the component. If you're using this component within a form field, don't set this property because the form field component automatically sets it.

Use this property if the component isn't using inlineLabelText and isn't surrounded by a form field, or you want to override the value automatically set by the form field (for example, if you have two components within a single form field).

To use it correctly, define an ID for the element you want to use as label and set the property to that ID.

aria-requiredboolean default: null

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.

disabledboolean

Determines whether the whole select component is disabled.

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.

inline-label-textstring

Adds a small label inline with the input for saving vertical space in the UI. For use with collection select filters only.

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-optionSelectProps.SelectOptionItemRenderer

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

selected-aria-labelstring default: ''

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-optionSelectProps.Option | nullrequired

Specifies the currently selected option. If you want to clear the selection, use null.

trigger-variantSelectProps.TriggerVariant

Defines the variant of the trigger. You can use a simple label or the entire option (label | option)

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<SelectProps.ChangeDetail>

Called when the user selects an option. The event detail contains the current selectedOption.

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