Autocomplete

A Base UI autocomplete composed with Notion-style menu groups, items, labels, and separators.

<Autocomplete items={groups} open autoHighlight="always" openOnInputClick>
<AutocompleteInput placeholder="Search workspace..." />
<AutocompleteContent>
  <AutocompleteEmpty>No matches found.</AutocompleteEmpty>
  <AutocompleteList>
    {(group) => (
      <AutocompleteGroup key={group.label} items={group.items}>
        <AutocompleteLabel title={group.label} />
        <AutocompleteCollection>
          {(item) => (
            <AutocompleteItem
              key={item}
              value={item}
              label={item}
              icon={group.icon}
            >
              <MenuItemAction className="text-xs text-muted">
                {group.label.slice(0, -1)}
              </MenuItemAction>
            </AutocompleteItem>
          )}
        </AutocompleteCollection>
      </AutocompleteGroup>
    )}
  </AutocompleteList>
</AutocompleteContent>
</Autocomplete>

<Autocomplete items={groups} open autoHighlight="always" openOnInputClick><AutocompleteInput placeholder="Search workspace..." /><AutocompleteContent>  <AutocompleteEmpty>No matches found.</AutocompleteEmpty>  <AutocompleteList>    {(group) => (      <AutocompleteGroup key={group.label} items={group.items}>        <AutocompleteLabel title={group.label} />        <AutocompleteCollection>          {(item) => (            <AutocompleteItem              key={item}              value={item}              label={item}              icon={group.icon}            >              <MenuItemAction className="text-xs text-muted">                {group.label.slice(0, -1)}              </MenuItemAction>            </AutocompleteItem>          )}        </AutocompleteCollection>      </AutocompleteGroup>    )}  </AutocompleteList></AutocompleteContent></Autocomplete>

Installation

pnpm add @notion-kit/ui

pnpm add @notion-kit/ui

Examples

Use AutocompleteContent variant="inline" when another primitive owns the overlay positioning. This keeps existing popover menus as Popover + Autocomplete.

<Popover>
<PopoverTrigger
  render={<Button variant="hint" size="sm">Open menu</Button>}
/>
<PopoverContent>
  <Autocomplete items={groups} open autoHighlight="always" openOnInputClick>
    <AutocompleteInput placeholder="Search workspace..." />
    <AutocompleteContent variant="inline">
      <AutocompleteEmpty>No matches found.</AutocompleteEmpty>
      <AutocompleteList>
        {(group) => (
          <AutocompleteGroup key={group.label} items={group.items}>
            <AutocompleteLabel title={group.label} />
            <AutocompleteCollection>
              {(item) => (
                <AutocompleteItem
                  key={item}
                  value={item}
                  label={item}
                  icon={group.icon}
                >
                  <MenuItemAction className="text-xs text-muted">
                    {group.label.slice(0, -1)}
                  </MenuItemAction>
                </AutocompleteItem>
              )}
            </AutocompleteCollection>
          </AutocompleteGroup>
        )}
      </AutocompleteList>
    </AutocompleteContent>
  </Autocomplete>
</PopoverContent>
</Popover>

<Popover><PopoverTrigger  render={<Button variant="hint" size="sm">Open menu</Button>}/><PopoverContent>  <Autocomplete items={groups} open autoHighlight="always" openOnInputClick>    <AutocompleteInput placeholder="Search workspace..." />    <AutocompleteContent variant="inline">      <AutocompleteEmpty>No matches found.</AutocompleteEmpty>      <AutocompleteList>        {(group) => (          <AutocompleteGroup key={group.label} items={group.items}>            <AutocompleteLabel title={group.label} />            <AutocompleteCollection>              {(item) => (                <AutocompleteItem                  key={item}                  value={item}                  label={item}                  icon={group.icon}                >                  <MenuItemAction className="text-xs text-muted">                    {group.label.slice(0, -1)}                  </MenuItemAction>                </AutocompleteItem>              )}            </AutocompleteCollection>          </AutocompleteGroup>        )}      </AutocompleteList>    </AutocompleteContent>  </Autocomplete></PopoverContent></Popover>

Anatomy

<Autocomplete>
  <AutocompleteInput />
  <AutocompleteContent>
    <AutocompleteEmpty />
    <AutocompleteList>
      <AutocompleteGroup>
        <AutocompleteLabel />
        <AutocompleteCollection>
          <AutocompleteItem />
        </AutocompleteCollection>
      </AutocompleteGroup>
    </AutocompleteList>
  </AutocompleteContent>
</Autocomplete>

For grouped root items, render groups from AutocompleteList:

<Autocomplete items={groups}>
  <AutocompleteInput />
  <AutocompleteContent>
    <AutocompleteEmpty />
    <AutocompleteList>
      {(group) => (
        <AutocompleteGroup items={group.items}>
          <AutocompleteLabel title={group.label} />
          <AutocompleteCollection>
            {(item) => <AutocompleteItem value={item} label={item} />}
          </AutocompleteCollection>
        </AutocompleteGroup>
      )}
    </AutocompleteList>
  </AutocompleteContent>
</Autocomplete>

API Reference

Autocomplete

The Base UI autocomplete root. It owns the input value, filtering, highlight state, and item collection.

Prop	Type	Default	Description
`items`	`Item[] \| { items: Item[] }[]`	-	Items to filter and render through `AutocompleteCollection`.
`itemToStringValue`	`(item: Item) => string`	-	Converts object items to searchable text.
`value`	`string`	-	Controlled input value.
`onValueChange`	`(value: string) => void`	-	Handler called when the input value changes.
`filter`	Base UI filter function	-	Optional custom filter. Prefer the internal filter by default.
`filteredItems`	`Item[] \| { items: Item[] }[]`	-	Controlled filtered result set.
`open`	`boolean`	-	Whether the autocomplete popup/list is open.
`autoHighlight`	`"always" \| "input" \| "none" \| boolean`	-	How Base UI highlights a matching item.
`openOnInputClick`	`boolean`	-	Opens the list when the input is clicked.

The search input uses Base UI Input and Clear. It includes a search icon and shows the native clear button when the input has text. Use an uncontrolled root unless the query also drives application behavior.

default renders a bordered field with inset spacing. flat renders a full-width header with a bottom divider. Both styles include the search icon and native clear button.

Prop	Type	Default	Description
`placeholder`	`string`	-	Placeholder text for the input.
`variant`	`"default" \| "flat"`	`"default"`	Bordered field or full-width header with a bottom divider.
`className`	`string`	-	Classes for the styled field container.

Other input props, including ref, render, and accessible labels, follow Base UI Input. AutocompleteInputProps exports this contract.

The former search, clear, and onCancel props and standalone AutocompleteClear export are removed. Observe changes through the root's onValueChange when the application needs the query. Native clearing uses that same callback.

AutocompleteContent

The popup surface. Floating content is positioned by Base UI; inline content renders in-flow for composed menus.

Prop	Type	Default	Description
`variant`	`"floating" \| "inline"`	`"floating"`	Whether to render a positioned popup or in-flow content.
`side`	`"top" \| "right" \| "bottom" \| "left"`	`"bottom"`	Preferred side for floating content.
`align`	`"start" \| "center" \| "end"`	`"start"`	Preferred alignment for floating content.
`sideOffset`	`number`	`4`	Distance from the anchor for floating content.
`alignOffset`	`number`	-	Alignment offset for floating content.
`collisionPadding`	`number \| Padding`	-	Padding used when avoiding viewport collisions.
`anchor`	Base UI anchor	-	Custom anchor for floating content.

AutocompleteList

The scrollable list viewport. When the root receives grouped items, pass a render function as children and render one AutocompleteGroup per group.

Prop	Type	Default	Description
`children`	`React.ReactNode \| ((item, index) => ReactNode)`	-	Static content or a Base UI item/group renderer.

AutocompleteCollection

Renders the filtered items from the nearest root or group.

Prop	Type	Default	Description
`children`	`(item, index) => ReactNode`	-	Renderer for each filtered item.

AutocompleteGroup

Groups related autocomplete items with menu spacing.

Prop	Type	Default	Description
`items`	`Item[]`	-	Group items. Use only when rendering a grouped root item from `AutocompleteList`.

For flat root items, keep the visual group item-less and let AutocompleteCollection read the root filtered items.

AutocompleteLabel

A non-interactive label used to title a group of items.

Prop	Type	Default	Description
`title`	`React.ReactNode`	-	The group label content.

AutocompleteItem

A single selectable autocomplete row. Extends the shared MenuItem visual props.

Prop	Type	Default	Description
`value`	`Item`	-	The item value selected by Base UI.
`label`	`React.ReactNode`	`String(value)`	The main item label.
`icon`	`React.ReactNode`	-	An optional leading icon.
`desc`	`string`	-	An optional description below the label.
`variant`	`"default" \| "secondary" \| "sidebar" \| "warning" \| "error"`	`"default"`	The visual style of the item.
`disabled`	`boolean`	-	Whether the item is disabled.
`onClick`	`React.MouseEventHandler<HTMLElement>`	-	Handler called when the item is clicked.

Use MenuItemAction as trailing content for metadata, status, or shortcuts.

Autocomplete

Installation

Examples

Popover Menu

Anatomy

API Reference

Autocomplete

AutocompleteInput

AutocompleteContent

AutocompleteList

AutocompleteCollection

AutocompleteGroup

AutocompleteLabel

AutocompleteItem

AutocompleteEmpty

AutocompleteSeparator

AutocompleteTrigger

AutocompleteStatus

On this page