Autocomplete API · slotsmith

Slots

Autocomplete has 22 slots. Pass a replacement for any of them in components; every slot you leave out keeps its fallback. Element slots receive DOM props, so a library's own element fits as it is; widget slots receive named props and usually need a few lines of adapter.

Name	Kind	Props it receives	Default fallback	`data-*` attributes
`Root`	<element>	DOM props: `Omit<HTMLAttributes<HTMLDivElement>, "color">` `ref?: Ref<HTMLDivElement>`	Fallback source `Root: ({ className, ...props }) => <div className={cx("sac", className)} {...props} />`	`data-disabled` `data-empty` `data-invalid` `data-open`
`Trigger`	<element>	DOM props: `Omit<HTMLAttributes<HTMLDivElement>, "color">` `ref?: Ref<HTMLDivElement>`	Fallback source `Trigger: ({ className, ...props }) => <div className={cx("sac__trigger", className)} {...props} />`	`data-disabled` `data-empty` `data-invalid` `data-open` `data-search-in`
`TriggerInput`	<element>	DOM props: `Omit<InputHTMLAttributes<HTMLInputElement>, "color" \| "size">` `ref?: Ref<HTMLInputElement>`	Fallback source `TriggerInput: ({ className, ...props }) => <input className={cx("sac__trigger-input", className)} {...props} />`	—
`Toggle`	<element>	DOM props: `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "color">` `ref?: Ref<HTMLButtonElement>`	Fallback source `Toggle: ({ className, ...props }) => <button className={cx("sac__toggle", className)} {...props} />`	`data-open`
`Value`	{widget}	`label?: string` The selected option's text, when there is one. `placeholder: string` Shown when nothing is selected. `empty: boolean` Whether anything is selected.	Fallback source `Value: ({ label, placeholder, empty }) => ( <span className={cx("sac__value", empty && "sac__value--empty")}>{empty ? placeholder : label}</span> )`	—
`Tag`	{widget}	`label: string` The option's text, falling back to its id when the option is unknown. `value: OptionValue` The id this tag stands for. `option?: TOption` The option behind it, when it is known. `onRemove: () => void` Removes just this value. `removeLabel: string` Accessible name for the remove control. `disabled: boolean` Whether the control is disabled.	Fallback source `Tag: ({ label, onRemove, removeLabel, disabled }) => ( <span className="sac__tag"> <span className="sac__tag-label">{label}</span> {!disabled && ( <button type="button" className="sac__tag-remove" aria-label={removeLabel} onClick={(event) => { event.stopPropagation(); onRemove(); }} > <CrossIcon /> </button> )} </span> )`	—
`Clear`	{widget}	`onClick: () => void` Clears the selection. `aria-label: string` Accessible name.	Fallback source `Clear: ({ onClick, ...aria }) => ( <button type="button" className="sac__clear" onClick={(event) => { event.stopPropagation(); onClick(); }} {...aria} > <CrossIcon /> </button> )`	—
`Indicator`	{widget}	`open: boolean` Whether the popup is open. `loading: boolean` Whether a first page is in flight.	Fallback source `Indicator: ({ loading }) => loading ? <span className="sac__spinner" aria-hidden="true" /> : <ChevronIcon />`	—
`Popup`	<element>	DOM props: `Omit<HTMLAttributes<HTMLDivElement>, "color">` `ref?: Ref<HTMLDivElement>`	Fallback source `Popup: ({ className, ...props }) => <div className={cx("sac__popup", className)} {...props} />`	`data-placement`
`Search`	<element>	DOM props: `Omit<InputHTMLAttributes<HTMLInputElement>, "color" \| "size">` `ref?: Ref<HTMLInputElement>`	Fallback source `Search: ({ className, ...props }) => <input className={cx("sac__search", className)} {...props} />`	—
`List`	<element>	DOM props: `Omit<HTMLAttributes<HTMLUListElement>, "color">` `ref?: Ref<HTMLUListElement>`	Fallback source `List: ({ className, ...props }) => <ul className={cx("sac__list", className)} {...props} />`	—
`Option`	<element>	DOM props: `Omit<LiHTMLAttributes<HTMLLIElement>, "color">` `ref?: Ref<HTMLLIElement>`	Fallback source `Option: ({ className, ...props }) => <li className={cx("sac__option", className)} {...props} />`	`data-disabled` `data-highlighted` `data-index` `data-selected`
`OptionLabel`	{widget}	`option: TOption` The whole option. `label: string` Its text, as `getOptionLabel` returned it. `selected: boolean` Whether it is selected. `highlighted: boolean` Whether it is the active option. `disabled: boolean` Whether it can be picked.	Fallback source `OptionLabel: ({ label }) => <span className="sac__label">{label}</span>`	—
`Check`	{widget}	`selected: boolean` Whether to render as selected.	Fallback source `Check: ({ selected }) => (selected ? <CheckIcon /> : null)`	—
`Group`	<element>	DOM props: `Omit<HTMLAttributes<HTMLUListElement>, "color">` `label: string` The group's name, which is also its label. `labelId: string` The id of the label element the group is labelled by. `children?: ReactNode` The label row, then the group's option rows. `ref?: Ref<HTMLUListElement>`	Fallback source `Group: ({ label: _label, labelId: _labelId, className, ...props }) => ( <li className="sac__group" role="none"> <ul className={cx("sac__group-list", className)} {...props} /> </li> )`	—
`GroupLabel`	{widget}	`id: string` The id the group's `aria-labelledby` points at. `role: "presentation"` Keeps the row from being read as a list item. `label: string` The group's name. `hidden?: boolean` Set on the copy a windowed list keeps for a group whose label row has scrolled away. Pass it on to the element: the group stays named through it, and it takes no space.	Fallback source `GroupLabel: ({ label, ...props }) => ( <li className="sac__group-label" {...props}> {label} </li> )`	—
`Separator`	<element>	DOM props: `Omit<LiHTMLAttributes<HTMLLIElement>, "color">` `ref?: Ref<HTMLLIElement>`	Fallback source `Separator: ({ className, ...props }) => <li className={cx("sac__separator", className)} {...props} />`	—
`Empty`	{widget}	`query: string` The current search text. `status: AutocompleteStatus` Why the list is empty. Either `empty` or `min-chars`. `message: string` The message for that reason.	Fallback source `Empty: ({ message }) => <li className="sac__message">{message}</li>`	—
`Loading`	{widget}	`message: string` The message.	Fallback source `Loading: ({ message }) => ( <li className="sac__message"> <span className="sac__spinner" aria-hidden="true" /> {message} </li> )`	—
`Error`	{widget}	`error: string` The message. `onRetry?: () => void` Retries, when the caller provided a way to. `retryLabel: string` Label for the retry control.	Fallback source `Error: ({ error, onRetry, retryLabel }) => ( <li className="sac__error"> <span>{error}</span> {onRetry ? ( <button type="button" className="sac__button" onClick={onRetry}> {retryLabel} </button> ) : null} </li> )`	—
`Create`	{widget}	`query: string` The text that would be created. `onCreate: () => void` Creates it. `loading: boolean` Whether the create request is in flight. `label: string` The rendered label, e.g. `Create "Acme"`.	Fallback source `Create: ({ onCreate, loading, label }) => ( <li className="sac__create"> <button type="button" className="sac__create-button" onClick={onCreate} disabled={loading}> <PlusIcon /> {label} </button> </li> )`	—
`LoadMore`	{widget}	`ref?: Ref<HTMLLIElement>` Attach to the element that should be observed. `onLoadMore: () => void` Requests the next page. `loading: boolean` Whether that page is already in flight. `label: string` The label for the current state.	Fallback source `LoadMore: ({ ref, onLoadMore, loading, label }) => ( <li ref={ref} className="sac__more"> <button type="button" className="sac__more-button" onClick={onLoadMore} disabled={loading}> {loading ? <span className="sac__spinner" aria-hidden="true" /> : null} {label} </button> </li> )`	—

Props

Every prop of Autocomplete, grouped as in the library's documentation. Controlled state comes in pairs: pass a value with its change handler, or only the default to leave the state inside the component.

Name	Type	Default	Description
Options
`options`required	`TOption[]`	—	The options to render.
`getOptionValue`	`GetOptionValue<TOption>`	—	Reads an option's id. Default: `option.value ?? option.id`. Every option's value must be unique: it keys the rows and builds their DOM ids, so two options with one value would share an id.
`getOptionLabel`	`GetOptionLabel<TOption>`	—	Reads an option's text. Default: `option.label ?? option.name`.
`optionDisabled`	`(option: TOption) => boolean`	—	Marks an option unselectable. It stays visible but cannot be landed on.
`getOptionGroup`	`GetOptionGroup<TOption>`	—	Reads the group an option belongs to, which is also the group's label. The options stay one flat list: groups appear in the order their first option does, an option joins its group wherever it sits (a later page included), and the options with no group form one unlabelled section where the first of them appeared. A group the search empties disappears with its label and separator. Read whenever the options or the search change.
`filter`	`OptionFilter<TOption>`	—	How to narrow options against the search. `false` filters nothing.
`selected`single mode	`TOption \| null`	—	The option behind `value`, for an id whose option is not in `options`.
`selected`multiple mode	`TOption[]`	—	The options behind `value`, for ids whose options are not in `options`.
Selection
`multiple`single mode	`false`	—	One value at a time.
`multiple`requiredmultiple mode	`true`	—	Several values, with the popup staying open on each pick.
`value`single mode	`OptionValue \| null`	—	The selected id, or `null` for nothing.
`value`multiple mode	`OptionValue[]`	—	The selected ids.
`defaultValue`single mode	`OptionValue \| null`	—	The selected id while uncontrolled.
`defaultValue`multiple mode	`OptionValue[]`	—	The selected ids while uncontrolled.
`onChange`single mode	`(value: OptionValue \| null, option?: TOption) => void`	—	The new id and, where known, the option behind it. `null` means cleared.
`onChange`multiple mode	`(values: OptionValue[], options: (TOption \| undefined)[]) => void`	—	The new ids, and the options index-aligned with them. An entry is `undefined` only when an id was supplied that no option has been seen for, so the two arrays always correspond.
`clearable`	`boolean`	—	Whether the clear control is offered. Default `true`.
`closeOnSelect`	`boolean`	`!multiple`	Whether picking closes the popup. Defaults to `!multiple`.
`name`	`string`	—	Renders a hidden input per value, so a plain HTML form submits it.
Search
`searchable`	`boolean`	—	Whether the search box renders. `false` makes it a select with typeahead.
`searchIn`	`"popup" \| "trigger"`	—	Where the search box sits. `"popup"` puts it at the top of the popup, behind a trigger that is a button. `"trigger"` makes the trigger an editable combobox: an input inside the field, which keeps focus the whole time, shows the picked label while closed in single mode, and sits after the tags in multiple mode. Ignored when `searchable` is `false`, which keeps the button trigger. Default `"popup"`.
`searchQuery`	`string`	—	The search text. With `searchIn="trigger"` the parent owns what the input shows while this is not empty, open or closed; the picked label returns once the parent sets it back to `""`, which a close asks for through `onSearchChange("")`.
`defaultSearchQuery`	`string`	—	The search text while uncontrolled.
`onSearchChange`	`(query: string) => void`	—	Told when the search text changes, for remote options.
`minChars`	`number`	—	Don't search until this many characters are typed.
Open state and keyboard
`open`	`boolean`	—	Whether the popup is open.
`defaultOpen`	`boolean`	—	Whether the popup starts open.
`onOpenChange`	`(open: boolean) => void`	—	Told when the popup opens or closes.
`loop`	`boolean`	—	Whether the highlight wraps past the ends. Default `false`.
`autoHighlight`	`boolean`	—	Highlight the first enabled option whenever the list opens or its contents change, so Enter picks the top match. A highlight the user moved themselves is kept until the search changes. Default `false`.
`disabled`	`boolean`	—	Nothing can be opened, picked or cleared.
`invalid`	`boolean`	—	The value failed validation. Sets `aria-invalid` on the combobox and `data-invalid` on the root and trigger, so a skin can show its error style. Pair it with `aria-errormessage` or `aria-describedby` pointing at the message. Default `false`.
`onBlur`	`(event: FocusEvent<HTMLElement>) => void`	—	Told when focus leaves the whole control, for form libraries.
Remote options
`loading`	`boolean`	—	A first page is in flight.
`error`	`string`	—	The last fetch failed. Replaces the list.
`onRetry`	`() => void`	—	Offers a way back from the error.
`hasMore`	`boolean`	—	Another page exists.
`onLoadMore`	`() => void`	—	Asks for the next page.
`loadingMore`	`boolean`	—	That next page is in flight.
Creating
`creatable`	`boolean`	—	Offers a "create <query>" row when the search matches nothing.
`onCreate`	`(query: string) => void`	—	Creates the searched name.
`createLoading`	`boolean`	—	The create request is in flight.
Rendering
`components`	`Partial<AutocompleteComponents<TOption>>`	—	Replace any part; the rest fall back to `SlotsmithProvider`'s `components.autocomplete`, then to the built-in ones.
`labels`	`Partial<AutocompleteLabels>`	—	Override any string. Wins over `locale`.
`locale`	`LocaleInput`	the provider's	The language: a locale object, or the tag of one given to `SlotsmithProvider`. Defaults to the provider's.
`slotProps`	`AutocompleteSlotProps`	—	Extra DOM props for the element parts.
`placeholder`	`string`	`labels.placeholder`	Trigger text when nothing is selected. Defaults to `labels.placeholder`.
`maxTags`	`number`	`2`	Tags shown before the rest collapse into `+N`. Defaults to 2.
`virtual`	`AutocompleteVirtualOptions`	—	Renders only the options in view, for lists of thousands: pass the virtualizer hook (`useVirtualizer` from `@tanstack/react-virtual`) as `use`, and the sizes.
Positioning
`placement`	`PopupPlacement`	`bottom`	Which side of the trigger the popup prefers. Defaults to `bottom`.
`popupOffset`	`number`	`4`	Gap between trigger and popup, in pixels. Defaults to 4.
`matchTriggerWidth`	`boolean`	`true`	Make the popup exactly as wide as the trigger. Defaults to `true`.
`popupMaxHeight`	`number`	`320`	Upper bound on the popup's height, in pixels. Defaults to 320.
`portal`	`PortalTarget`	`false`	Renders the popup in a portal: `true` for `document.body`, or an element of your own. It then escapes any ancestor's `overflow`, `transform` or stacking context, and still counts as part of the control. Set the `--ss-*` tokens and the dark class on `:root` or on that element, which the popup then inherits from. Defaults to `false`.

Any other prop is passed to the root <div> element.

Labels & locales

Every string Autocomplete shows or announces, with its English default. Pass labels to change some of them for one component, or locale to switch every string to another language. The demo below does both.

Key	Type	English default	Description
`placeholder`	`string`	`"Select…"`	Trigger text when nothing is selected.
`search`	`string`	`"Search…"`	Placeholder for the search box.
`clear`	`string`	`"Clear selection"`	Accessible name for the clear control.
`toggle`	`string`	`"Show options"`	Accessible name for the button that opens and closes the list, with `searchIn="trigger"`.
`remove`	`(label: string) => string`	`remove("Lisbon")` prints `"Remove Lisbon"`	Accessible name for a tag's remove control.
`empty`	`string`	`"No results"`	Shown when a search returned nothing.
`loading`	`string`	`"Loading…"`	Shown while a first page is loading.
`minChars`	`(count: number) => string`	`minChars(3)` prints `"Type 3 or more characters to search"`	Shown before `minChars` characters have been typed.
`retry`	`string`	`"Retry"`	Label for the retry control.
`create`	`(query: string) => string`	`create("Lis")` prints `"Create “Lis”"`	Label for the create row.
`creating`	`string`	`"Creating…"`	Label for the create row while the request is in flight.
`more`	`(count: number) => string`	`more(3)` prints `"+3"`	The overflow badge in multiple mode.
`loadMore`	`string`	`"Load more"`	Label for the load-more control.
`results`	`(count: number) => string`	`results(3)` prints `"3 results"`	Announced to screen readers when the result count changes.

import { Autocomplete } from "slotsmith/autocomplete";
import { de } from "slotsmith/locales/de";

const cities = [
  { value: "berlin", label: "Berlin" },
  { value: "hamburg", label: "Hamburg" },
  { value: "koeln", label: "Köln" },
  { value: "leipzig", label: "Leipzig" },
  { value: "muenchen", label: "München" },
];

export default function Labels() {
  return (
    <Autocomplete
      options={cities}
      // Every string in German, from the ready-made pack…
      locale={de}
      // …except these two, replaced for this picker only.
      labels={{ placeholder: "Stadt wählen…", empty: "Keine Stadt gefunden" }}
      aria-label="Stadt"
      style={{ maxWidth: 320 }}
    />
  );
}

The ready-made language packs, right-to-left support and app-wide locales are on the Languages page.

Styling

The class names the fallbacks of Autocomplete put on their elements, and the tokens its stylesheet reads. Set a token on the component, or on any element around it, to restyle it; target a class only for what no token covers.

Class	Slot
`.sac`	`Root`
`.sac__body`	—
`.sac__overflow`	—
`.sac__sr-only`	—
`.sac__chevron`	`Indicator`
`.sac__tick`	`Check`
`.sac__cross`	—
`.sac__plus`	—
`.sac__tag`	`Tag`
`.sac__tag-label`	—
`.sac__tag-remove`	—
`.sac__clear`	`Clear`
`.sac__spinner`	—
`.sac__label`	`OptionLabel`
`.sac__message`	`Empty` `Loading`
`.sac__error`	`Error`
`.sac__button`	—
`.sac__create`	`Create`
`.sac__create-button`	—
`.sac__more`	`LoadMore`
`.sac__more-button`	—
`.sac__trigger`	`Trigger`
`.sac__trigger-input`	`TriggerInput`
`.sac__toggle`	`Toggle`
`.sac__value`	`Value`
`.sac__value--empty`	—
`.sac__popup`	`Popup`
`.sac__search`	`Search`
`.sac__list`	`List`
`.sac__option`	`Option`
`.sac__group`	`Group`
`.sac__group-list`	—
`.sac__group-label`	`GroupLabel`
`.sac__separator`	`Separator`

Token	Layer
`--sac-accent`	This component
`--sac-border`	This component
`--sac-danger`	This component
`--sac-font-size`	This component
`--sac-hover`	This component
`--sac-muted`	This component
`--sac-radius`	This component
`--sac-surface`	This component
`--sac-text`	This component
`--ss-accent`	Shared by every component
`--ss-border`	Shared by every component
`--ss-danger`	Shared by every component
`--ss-font-size`	Shared by every component
`--ss-hover`	Shared by every component
`--ss-muted`	Shared by every component
`--ss-radius`	Shared by every component
`--ss-surface`	Shared by every component
`--ss-text`	Shared by every component

Every token switches to its dark value under .dark, [data-theme="dark"], on the page or on any element around the component.

Theming covers the tokens and the ready-made themes.