import { Autocomplete } from 'gnome-ui/autocomplete';
import { Tag } from 'lucide-react';

const labels = [
  { id: 't1', value: 'feature' },
  { id: 't2', value: 'fix' },
  { id: 't3', value: 'bug' },
  { id: 't4', value: 'docs' },
  { id: 't5', value: 'internal' },
  { id: 't6', value: 'mobile' },
  { id: 'c-accordion', value: 'component: accordion' },
  { id: 'c-alert-dialog', value: 'component: alert dialog' },
  { id: 'c-autocomplete', value: 'component: autocomplete' },
  { id: 'c-avatar', value: 'component: avatar' },
];

function AutocompleteDefault() {
  return (
    <Autocomplete.Root items={labels}>
      <label className="flex flex-col gap-1.5">
        <span className="text-xs font-semibold uppercase tracking-widest text-muted-foreground">
          Labels
        </span>
        <div className="relative flex items-center">
          <Tag className="pointer-events-none absolute left-3 size-4 text-muted-foreground" />
          <Autocomplete.Input
            placeholder="Search labels…"
            className="h-10 w-72 rounded-xl border border-input bg-card pl-9 pr-3.5 text-sm text-foreground placeholder:text-muted-foreground transition-colors duration-150 hover:border-ring/50 focus:outline focus:outline-2 focus:-outline-offset-1 focus:outline-ring"
          />
        </div>
      </label>

      <Autocomplete.Portal>
        <Autocomplete.Positioner sideOffset={6} className="outline-none">
          <Autocomplete.Popup className="w-[var(--anchor-width)] overflow-hidden rounded-xl border border-border bg-card shadow-lg outline-none">
            <Autocomplete.List className="max-h-[min(15rem,var(--available-height))] overflow-y-auto py-1.5 outline-none">
              {(label) => (
                <Autocomplete.Item
                  key={label.id}
                  value={label}
                  className="relative flex cursor-default items-center gap-2.5 px-3 py-2 text-sm text-foreground outline-none select-none transition-colors duration-100 data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground"
                >
                  <Tag className="size-3.5 shrink-0 text-muted-foreground" />
                  {label.value}
                </Autocomplete.Item>
              )}
            </Autocomplete.List>
          </Autocomplete.Popup>
        </Autocomplete.Positioner>
      </Autocomplete.Portal>
    </Autocomplete.Root>
  );
}

Anatomy

import { Autocomplete } from 'gnome-ui/autocomplete';

<Autocomplete.Root>
  <Autocomplete.Input />
  <Autocomplete.Trigger />
  <Autocomplete.Icon />
  <Autocomplete.Clear />

  <Autocomplete.Portal>
    <Autocomplete.Backdrop />
    <Autocomplete.Positioner>
      <Autocomplete.Popup>
        <Autocomplete.Empty />
        <Autocomplete.List> 
            <Autocomplete.Item /> 
        </Autocomplete.List>
      </Autocomplete.Popup>
    </Autocomplete.Positioner>
  </Autocomplete.Portal>
</Autocomplete.Root>

Examples

Grouped

Items organized by category using Autocomplete.Group and Autocomplete.GroupLabel, inspired by GNOME Settings search with section headings.

import { Autocomplete } from 'gnome-ui/autocomplete';
import { Search, Settings } from 'lucide-react';

const settingGroups = [
  {
    value: 'System',
    items: [
      { id: 's1', value: 'Display & Brightness' },
      { id: 's2', value: 'Sound' },
      { id: 's3', value: 'Power' },
      { id: 's4', value: 'Notifications' },
    ],
  },
  {
    value: 'Connectivity',
    items: [
      { id: 'c1', value: 'Wi-Fi' },
      { id: 'c2', value: 'Bluetooth' },
      { id: 'c3', value: 'VPN' },
    ],
  },
  {
    value: 'User',
    items: [
      { id: 'u1', value: 'Privacy & Security' },
      { id: 'u2', value: 'User Accounts' },
      { id: 'u3', value: 'Online Accounts' },
    ],
  },
];

function AutocompleteGrouped() {
  return (
    <Autocomplete.Root items={settingGroups}>
      <label className="flex flex-col gap-1.5">
        <span className="text-xs font-semibold uppercase tracking-widest text-muted-foreground">
          Settings
        </span>
        <div className="relative flex items-center">
          <Search className="pointer-events-none absolute left-3 size-4 text-muted-foreground" />
          <Autocomplete.Input
            placeholder="Search settings…"
            className="h-10 w-72 rounded-xl border border-input bg-card pl-9 pr-3.5 text-sm text-foreground placeholder:text-muted-foreground transition-colors duration-150 hover:border-ring/50 focus:outline focus:outline-2 focus:-outline-offset-1 focus:outline-ring"
          />
        </div>
      </label>

      <Autocomplete.Portal>
        <Autocomplete.Positioner sideOffset={6} className="outline-none">
          <Autocomplete.Popup className="w-[var(--anchor-width)] overflow-hidden rounded-xl border border-border bg-card shadow-lg outline-none">
            <Autocomplete.List className="max-h-[min(18rem,var(--available-height))] overflow-y-auto py-1.5 outline-none">
              {(group) => (
                <Autocomplete.Group key={group.value}>
                  <Autocomplete.GroupLabel className="flex items-center gap-2 px-3 pb-1 pt-2.5 text-[11px] font-semibold uppercase tracking-widest text-primary">
                    <Settings className="size-3 shrink-0" />
                    {group.value}
                  </Autocomplete.GroupLabel>
                  {group.items.map((item) => (
                    <Autocomplete.Item
                      key={item.id}
                      value={item}
                      className="relative flex cursor-default items-center gap-2.5 py-2 pl-7 pr-3 text-sm text-foreground outline-none select-none transition-colors duration-100 data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground"
                    >
                      {item.value}
                    </Autocomplete.Item>
                  ))}
                  <Autocomplete.Separator className="my-1 h-px bg-border last:hidden" />
                </Autocomplete.Group>
              )}
            </Autocomplete.List>
          </Autocomplete.Popup>
        </Autocomplete.Positioner>
      </Autocomplete.Portal>
    </Autocomplete.Root>
  );
}

---

With Clear & Trigger

A full-featured autocomplete with a dropdown trigger button and a clear button to reset the value, inspired by GNOME's search entry with auxiliary controls.

import { Autocomplete } from 'gnome-ui/autocomplete';
import { Globe, ChevronDown, X } from 'lucide-react';

const timezones = [
  { id: 'tz1', value: 'America/New_York' },
  { id: 'tz2', value: 'America/Chicago' },
  { id: 'tz3', value: 'America/Denver' },
  { id: 'tz4', value: 'America/Los_Angeles' },
  { id: 'tz5', value: 'Europe/London' },
  { id: 'tz6', value: 'Europe/Paris' },
  { id: 'tz7', value: 'Europe/Berlin' },
  { id: 'tz8', value: 'Asia/Tokyo' },
  { id: 'tz9', value: 'Asia/Shanghai' },
  { id: 'tz10', value: 'Australia/Sydney' },
];

function AutocompleteClear() {
  return (
    <Autocomplete.Root items={timezones}>
      <label className="flex flex-col gap-1.5">
        <span className="text-xs font-semibold uppercase tracking-widest text-muted-foreground">
          Timezone
        </span>
        <div className="relative flex items-center">
          <Globe className="pointer-events-none absolute left-3 size-4 shrink-0 text-muted-foreground" />
          <Autocomplete.Input
            placeholder="Select a timezone…"
            className="h-10 w-72 rounded-xl border border-input bg-card pl-9 pr-16 text-sm text-foreground placeholder:text-muted-foreground transition-colors duration-150 hover:border-ring/50 focus:outline focus:outline-2 focus:-outline-offset-1 focus:outline-ring"
          />
          <Autocomplete.Clear className="absolute right-8 flex h-5 w-5 items-center justify-center rounded-full bg-muted text-muted-foreground opacity-0 transition-opacity duration-150 hover:bg-accent hover:text-foreground focus-visible:outline focus-visible:outline-2 focus-visible:outline-ring [[data-has-value]_&]:opacity-100">
            <X className="size-3" />
          </Autocomplete.Clear>
          <Autocomplete.Trigger className="absolute right-2 flex h-6 w-6 items-center justify-center rounded-md text-muted-foreground transition-colors duration-150 hover:bg-accent hover:text-foreground focus-visible:outline focus-visible:outline-2 focus-visible:outline-ring data-[popup-open]:text-foreground">
            <ChevronDown className="size-4 transition-transform duration-200 data-[popup-open]:rotate-180" />
          </Autocomplete.Trigger>
        </div>
      </label>

      <Autocomplete.Portal>
        <Autocomplete.Positioner sideOffset={6} className="outline-none">
          <Autocomplete.Popup className="w-[var(--anchor-width)] overflow-hidden rounded-xl border border-border bg-card shadow-lg outline-none">
            <Autocomplete.List className="max-h-[min(15rem,var(--available-height))] overflow-y-auto py-1.5 outline-none">
              {(tz) => (
                <Autocomplete.Item
                  key={tz.id}
                  value={tz}
                  className="relative flex cursor-default items-center gap-2.5 px-3 py-2 text-sm text-foreground outline-none select-none transition-colors duration-100 data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground"
                >
                  <Globe className="size-3.5 shrink-0 text-muted-foreground" />
                  {tz.value}
                </Autocomplete.Item>
              )}
            </Autocomplete.List>
          </Autocomplete.Popup>
        </Autocomplete.Positioner>
      </Autocomplete.Portal>
    </Autocomplete.Root>
  );
}

Autocomplete

An input that suggests options as you type.

AutocompleteRoot

Groups all parts of the autocomplete. Doesn't render its own HTML element.

Documentation: Base UI Autocomplete

API reference

Root

Groups all parts of the autocomplete. Doesn't render its own HTML element.

Root Props:

• both: items are dynamically filtered based on the input value, which will temporarily change based on the active item (inline autocompletion).
• inline: items are static (not filtered), and the input value will temporarily change based on the active item (inline autocompletion).
• none: items are static (not filtered), and the input value will not change based on the active item. | | onItemHighlighted | ((highlightedValue: ItemValue \| undefined, eventDetails: Autocomplete.Root.HighlightEventDetails) => void) | - | Callback fired when an item is highlighted or unhighlighted. Receives the highlighted item value (or undefined if no item is highlighted) and event details with a reason property describing why the highlight changed. The reason can be:* 'keyboard': the highlight changed due to keyboard navigation.
• 'pointer': the highlight changed due to pointer hovering.
• 'none': the highlight changed programmatically. | | onOpenChangeComplete | ((open: boolean) => void) | - | Event handler called after any animations complete when the popup is opened or closed. | | openOnInputClick | boolean | false | Whether the popup opens when clicking the input. | | submitOnItemClick | boolean | false | Whether clicking an item should submit the autocomplete's owning form. By default, clicking an item via a pointer or Enter key does not submit the owning form. Useful when the autocomplete is used as a single-field form search input. | | virtualized | boolean | false | Whether the items are being externally virtualized. | | disabled | boolean | false | Whether the component should ignore user interaction. | | readOnly | boolean | false | Whether the user should be unable to choose a different option from the popup. | | required | boolean | false | Whether the user must choose a value before submitting a form. | | inputRef | Ref<HTMLInputElement> | - | A ref to the hidden input element. | | id | string | - | The id of the component. | | children | ReactNode | - | - |

Value

The current value of the autocomplete. Doesn't render its own HTML element.

Value Props:

Input

A text input to search for items in the list. Renders an <input> element.

Input Props:

Input Data Attributes:

Trigger

A button that opens the popup. Renders a <button> element.

Trigger Props:

Trigger Data Attributes:

Icon

An icon that indicates that the trigger button opens the popup. Renders a <span> element.

Icon Props:

Clear

Clears the value when clicked. Renders a <button> element.

Clear Props:

Clear Data Attributes:

List

A list container for the items. Renders a <div> element.

List Props:

Portal

A portal element that moves the popup to a different part of the DOM. By default, the portal element is appended to <body>. Renders a <div> element.

Portal Props:

Backdrop

An overlay displayed beneath the popup. Renders a <div> element.

Backdrop Props:

Backdrop Data Attributes:

Positioner

Positions the popup against the trigger. Renders a <div> element.

Positioner Props:

• data.positioner: the dimensions of the positioner element with properties width and height.
• data.side: which side of the anchor element the positioner is aligned against.
• data.align: how the positioner is aligned relative to the specified side. | | side | Side | 'bottom' | Which side of the anchor element to align the popup against. May automatically change to avoid collisions. | | sideOffset | number \| OffsetFunction | 0 | Distance between the anchor and the popup in pixels. Also accepts a function that returns the distance to read the dimensions of the anchor and positioner elements, along with its side and alignment.The function takes a data object parameter with the following properties:* data.anchor: the dimensions of the anchor element with properties width and height.
• data.positioner: the dimensions of the positioner element with properties width and height.
• data.side: which side of the anchor element the positioner is aligned against.
• data.align: how the positioner is aligned relative to the specified side. | | arrowPadding | number | 5 | Minimum distance to maintain between the arrow and the edges of the popup.Use it to prevent the arrow element from hanging out of the rounded corners of a popup. | | anchor | Element \| VirtualElement \| RefObject<Element \| null> \| (() => Element \| VirtualElement \| null) \| null | - | An element to position the popup against. By default, the popup will be positioned against the trigger. | | collisionAvoidance | CollisionAvoidance | - | Determines how to handle collisions when positioning the popup. | | collisionBoundary | Boundary | 'clipping-ancestors' | An element or a rectangle that delimits the area that the popup is confined to. | | collisionPadding | Padding | 5 | Additional space to maintain from the edge of the collision boundary. | | sticky | boolean | false | Whether to maintain the popup in the viewport after the anchor element was scrolled out of view. | | positionMethod | 'absolute' \| 'fixed' | 'absolute' | Determines which CSS position property to use. | | className | string \| ((state: Combobox.Positioner.State) => string \| undefined) | - | CSS class applied to the element, or a function that returns a class based on the component’s state. | | style | CSSProperties \| ((state: Combobox.Positioner.State) => CSSProperties \| undefined) | - | - | | render | ReactElement \| ((props: HTMLProps, state: Combobox.Positioner.State) => ReactElement) | - | 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. |

Positioner Data Attributes:

Positioner CSS Variables:

Popup

A container for the list. Renders a <div> element.

Popup Props:

• 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 \| RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => boolean \| void \| HTMLElement \| null) | - | 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: Combobox.Popup.State) => string \| undefined) | - | CSS class applied to the element, or a function that returns a class based on the component’s state. | | style | CSSProperties \| ((state: Combobox.Popup.State) => CSSProperties \| undefined) | - | - | | render | ReactElement \| ((props: HTMLProps, state: Combobox.Popup.State) => ReactElement) | - | 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. |

Popup Data Attributes:

Arrow

Displays an element positioned against the anchor. Renders a <div> element.

Arrow Props:

Arrow Data Attributes:

Status

Displays a status message whose content changes are announced politely to screen readers. Useful for conveying the status of an asynchronously loaded list. Renders a <div> element.

Status Props:

Empty

Renders its children only when the list is empty. Requires the items prop on the root component. Announces changes politely to screen readers. Renders a <div> element.

Empty Props:

Collection

Renders filtered list items. Doesn't render its own HTML element.If rendering a flat list, pass a function child to the List component instead, which implicitly wraps it.

Collection Props:

Row

Displays a single row of items in a grid list. Enable grid on the root component to turn the listbox into a grid. Renders a <div> element.

Row Props:

Item

An individual item in the list. Renders a <div> element.

Item Props:

Item Data Attributes:

Group

Groups related items with the corresponding label. Renders a <div> element.

Group Props:

GroupLabel

An accessible label that is automatically associated with its parent group. Renders a <div> element.

GroupLabel Props:

Separator

A separator element accessible to screen readers. Renders a <div> element.

Separator Props:

useFilter

Matches items against a query using Intl.Collator for robust string matching. This hook is used when externally filtering items.

Input parameters

Accepts all Intl.CollatorOptions, plus the following option:

Props:

Return value

Return Value:

useFilteredItems

Returns the internally filtered items when called inside <Autocomplete.Root>.

Return value

Return Value: