Preview

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

Usage

<cs-autosuggest placeholder="Search..."></cs-autosuggest>

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

Properties

aria-labelstring default: null

Adds an aria-label to the native control.

Use this if you don't have a visible label for this control.

aria-requiredboolean

Specifies whether to add aria-required to the native control.

auto-focusboolean

Indicates whether the control should be focused as soon as the page loads, which enables the user to start typing without having to manually focus the control. Don't use this option on pages where the control may be scrolled out of the viewport.

clear-aria-labelstring

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

disable-browser-autocorrectboolean

Specifies whether to disable browser autocorrect and related features. If you set this to true, it disables any native browser capabilities that automatically correct user input, such as autocorrect and autocapitalize. If you don't set it, the behavior follows the default behavior of the user's browser.

disabledboolean

Specifies if the control is disabled, which prevents the user from modifying the value and prevents the value from being included in a form submission. A disabled control can't receive focus.

entered-text-labelAutosuggestProps.EnteredTextLabel

Specifies a function that generates the custom value indicator (for example, Use "${value}").

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

Note that the matchesCount includes the enteredTextLabel ("Use ${value}") item, so in most cases you should subtract 1 from matchesCount. If using manual filtering, you should provide your own value for totalCount.

filtering-typeOptionsFilteringType default: 'auto'

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-entered-text-optionboolean

Defines whether entered text option is shown as the first option in the dropdown when value is non-empty.

namestring

Specifies the name of the control used in HTML forms.

optionsAutosuggestProps.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.
• label (string) - (Optional) Option text displayed to the user.
• lang (string) - (Optional) The language of the option, provided as a BCP 47 language tag.
• description (string) - (Optional) Further information about the option that appears below the label.
• disabled (boolean) - (Optional) Determines whether the option is disabled.
• 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.
• 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.
• 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.

OptionGroup

• label (string) - Option group text displayed to the user.
• disabled (boolean) - (Optional) Determines whether the option group is disabled.
• options (Option[]) - (Optional) The options under this group.

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 placeholder text rendered when the value is an empty string.

read-onlyboolean default: false

Specifies if the control is read-only, which prevents the user from modifying the value but includes it in a form submission. A read-only control can receive focus.

Don't use read-only inputs outside a form.

render-highlighted-aria-liveAutosuggestProps.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-optionAutosuggestProps.ItemRenderer

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

The item inside the props has a different shape depending on its type:

item

• type ('item') - The item type.
• index (number) - The item's absolute position in the dropdown.
• option (Option) - The original option configuration.
• disabled (boolean) - Whether the item is disabled.
• highlighted (boolean) - Whether the item is currently highlighted.
• selected (boolean) - Whether the item is selected.
• parent (OptionGroupRenderItem | null) - The parent group item, if any.

group

• type ('group') - The item type.
• index (number) - The item's absolute position in the dropdown.
• option (OptionGroup) - The original option configuration.
• disabled (boolean) - Whether the item is disabled.

entered-text

• type ('entered-text') - The item type.
• option (Option) - The entered-text option configuration.

When providing a custom renderOption implementation, it fully replaces the default visual rendering and content for that item. The component still manages focus, keyboard interactions, and selection state, but it no longer applies its default item layout or typography.

When returning null, the default rendering will be applied for that item.

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.

valuestringrequired

Specifies the text entered into the form element.

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

empty

Specifies the text that's displayed when there aren't any suggestions to display. This is displayed when statusType is set to finished or it's not set at all.

Events

blurCustomEvent<null>

Called when input focus is removed from the UI control.

changeCustomEvent<InputProps.ChangeDetail>

Called whenever a user changes the input value (by typing or pasting). The event detail contains the current value of the field.

focusCustomEvent<null>

Called when input focus is moved to the UI control.

keyDownCustomEvent<InputProps.KeyDetail>

Called when the underlying native textarea emits a keydown event. The event detail contains the keyCode and information about modifiers (that is, CTRL, ALT, SHIFT, META, etc.).

keyUpCustomEvent<InputProps.KeyDetail>

Called when the underlying native textarea emits a keyup event. The event detail contains the keyCode and information about modifiers (that is, CTRL, ALT, SHIFT, META, etc.).

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

selectCustomEvent<AutosuggestProps.SelectDetail>

Called whenever a user selects an option in the dropdown. Don't use this event as the only way to handle user input. Instead, use onSelect in combination with the onChange handler only as an optional convenience for the user.