Autocomplete

On this page

Audience

Custom audience names are allowed.

A text input whose suggestions do not restrict what can be entered.

Code

import { Autocomplete } from "@bosunkit/components/autocomplete";
import { Field } from "@bosunkit/components/field";
import type { ReactElement } from "react";
const items: readonly string[] = ["Engineering", "Product", "Investors"];
export const description: string =
  "Choose a familiar audience or enter another name; the value remains the input text.";
export default function Showcase(): ReactElement {
  return (
    <Field.Root>
      <Field.Label>Audience</Field.Label>
      <Autocomplete.Root items={items}>
        <Autocomplete.Input placeholder="Choose or type an audience" />
        <Autocomplete.Portal>
          <Autocomplete.Positioner sideOffset={4}>
            <Autocomplete.Popup>
              <Autocomplete.List>
                {(item: string): ReactElement => (
                  <Autocomplete.Item key={item} value={item}>
                    {item}
                  </Autocomplete.Item>
                )}
              </Autocomplete.List>
            </Autocomplete.Popup>
          </Autocomplete.Positioner>
        </Autocomplete.Portal>
      </Autocomplete.Root>
      <Field.Description>Custom audience names are allowed.</Field.Description>
    </Field.Root>
  );
}

01Names describe behaviorUse the primitive for custom composition and a named recipe for an assembled control.

02One state contractControlled values, defaults and change callbacks follow Base UI; event details keep their reason and cancellation.

03Composition keeps semanticsA render target forwards its ref and every received DOM prop so keyboard interaction and accessible names survive.

Composition

Import { Autocomplete } from @bosunkit/components/autocomplete. Named parts follow Base UI Autocomplete. Each part retains the upstream render, ref, DOM props, state attributes and event contracts. The kit supplies its typography, surfaces and scoped overlay presentation.

Examples

Custom composition

Audience

Custom audience names are allowed.

Choose a familiar audience or enter another name; the value remains the input text.

Code

import { Autocomplete } from "@bosunkit/components/autocomplete";
import { Field } from "@bosunkit/components/field";
import type { ReactElement } from "react";
const items: readonly string[] = ["Engineering", "Product", "Investors"];
export const description: string =
  "Choose a familiar audience or enter another name; the value remains the input text.";
export default function Showcase(): ReactElement {
  return (
    <Field.Root>
      <Field.Label>Audience</Field.Label>
      <Autocomplete.Root items={items}>
        <Autocomplete.Input placeholder="Choose or type an audience" />
        <Autocomplete.Portal>
          <Autocomplete.Positioner sideOffset={4}>
            <Autocomplete.Popup>
              <Autocomplete.List>
                {(item: string): ReactElement => (
                  <Autocomplete.Item key={item} value={item}>
                    {item}
                  </Autocomplete.Item>
                )}
              </Autocomplete.List>
            </Autocomplete.Popup>
          </Autocomplete.Positioner>
        </Autocomplete.Portal>
      </Autocomplete.Root>
      <Field.Description>Custom audience names are allowed.</Field.Description>
    </Field.Root>
  );
}

Props

Prop	Type	Default	Description
disabled	boolean \| undefined	–	Whether the component should ignore user interaction.
className	string \| ((state: State) => string \| undefined) \| undefined	–	CSS class applied to the element, or a function that returns a class based on the component's state.
render	React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> \| undefined	–	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) \| undefined	–	Style applied to the element, or a function that returns a style object based on the component's state.

Also takes every attribute of Primitive.Input.Props.

Prop	Type	Default	Description
initialFocus	boolean \| React.RefObject<HTMLElement \| null> \| ((openType: InteractionType) => void \| boolean \| HTMLElement \| null) \| undefined	–	Determines the element to focus when the popup is opened. - `false`: Do not move focus. - `true`: Move focus based on the default behavior (first tabbable element or popup). - `RefObject`: Move focus to the ref element. - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, or `false`/`undefined` to do nothing.
finalFocus	boolean \| React.RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => void \| boolean \| HTMLElement \| null) \| undefined	–	Determines the element to focus when the popup is closed. - `false`: Do not move focus. - `true`: Move focus based on the default behavior (trigger or previously focused element). - `RefObject`: Move focus to the ref element. - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, or `false`/`undefined` to do nothing.
className	string \| ((state: State) => string \| undefined) \| undefined	–	CSS class applied to the element, or a function that returns a class based on the component's state.
render	React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> \| undefined	–	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) \| undefined	–	Style applied to the element, or a function that returns a style object based on the component's state.

Also takes every attribute of Primitive.Popup.Props.

Prop	Type	Default	Description
children	React.ReactNode	–
onClick	BaseUIComponentProps<'div', AutocompleteItemState>['onClick'] \| undefined	–	An optional click handler for the item when selected. It fires when clicking the item with the pointer, as well as when pressing `Enter` with the keyboard if the item is highlighted when the `Input` or `List` element has focus.
index	number \| undefined	–	The index of the item in the list. Improves performance when specified by avoiding the need to calculate the index automatically from the DOM.
value	any	–	A unique value that identifies this item.
disabled	boolean \| undefined	–	Whether the component should ignore user interaction.
className	string \| ((state: State) => string \| undefined) \| undefined	–	CSS class applied to the element, or a function that returns a class based on the component's state.
render	React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> \| undefined	–	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) \| undefined	–	Style applied to the element, or a function that returns a style object based on the component's state.
nativeButton	boolean \| undefined	–	Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button.

Also takes every attribute of Primitive.Item.Props.

Prop	Type	Default	Description
children	React.ReactNode \| ((item: any, index: number) => React.ReactNode)	–
className	string \| ((state: State) => string \| undefined) \| undefined	–	CSS class applied to the element, or a function that returns a class based on the component's state.
render	React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> \| undefined	–	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) \| undefined	–	Style applied to the element, or a function that returns a style object based on the component's state.

Also takes every attribute of Primitive.List.Props.

Asynchronous suggestions

Audience

The lookup is caller-owned and abortable; this local specimen returns suggestions without a network request.

Code

import { AsyncAutocomplete, type Suggestion } from "@bosunkit/components/autocomplete";
import { FormField } from "@bosunkit/components/form-field";
import type { ReactElement } from "react";
export const description: string =
  "The lookup is caller-owned and abortable; this local specimen returns suggestions without a network request.";
export default function AsyncExample(): ReactElement {
  return (
    <FormField label="Audience">
      <AsyncAutocomplete
        minQueryLength={1}
        suggest={(query: string): Promise<readonly Suggestion[]> =>
          Promise.resolve(
            ["Engineering", "Product", "Investors"]
              .filter((label: string): boolean => label.toLowerCase().includes(query.toLowerCase()))
              .map((label: string): Suggestion => ({ label, value: label })),
          )
        }
      />
    </FormField>
  );
}

AsyncAutocomplete accepts suggest(query, signal) and minQueryLength. The caller owns the lookup; superseded requests are aborted and late answers are ignored. The callback keeps Base UI's cancellable event details.

Prop	Type	Default	Description
suggestrequired	(query: string, signal: AbortSignal) => Promise<readonly Suggestion[]>	–	Caller-owned asynchronous lookup; no transport belongs to the kit.
minQueryLength	number \| undefined	–	Minimum trimmed query length.
itemToStringValue	((item: Suggestion) => string) \| undefined	(item: Suggestion): string => item.label	Text inserted when choosing a suggestion; display label by default.
value	string \| undefined	–	Text value; arbitrary text remains valid.
defaultValue	string \| undefined	–	Initial text when uncontrolled.
onValueChange	Base.Root.Props<Suggestion>["onValueChange"]	–	Original cancellable Base UI text-change event.
onBlur	Base.Input.Props["onBlur"]	–	Input blur handler, preserving the native focus event.
id	string \| undefined	–	Control ID for an external label.
aria-label	string \| undefined	–	Accessible control name when no visible label is associated.
aria-describedby	string \| undefined	–	Hint and error element IDs.
placeholder	string \| undefined	–	Input placeholder.
readOnly	boolean \| undefined	–	Prevent editing.
disabled	boolean \| undefined	–	Prevent interaction and form submission.
name	string \| undefined	–	Submitted field name.
motion	boolean \| undefined	true	Enable popup entrance motion.
className	string \| undefined	–	Input classes.
ref	Ref<HTMLInputElement> \| undefined	–	Input element.

Audience

Custom audience names are allowed.

Compose labeled parts and preserve their ref and DOM props.

Don't

Use the named parts for keyboard and focus behavior.

Do not replace semantic controls with clickable generic elements or discard event details.

Component API: naming, state, composition and compatibility.
Interaction states: focus, disabled and selected presentation.
Form field: the assembled label and validation recipe.

Composition

Examples

Custom composition

Props

Asynchronous suggestions

Related