Autocomplete

Installation

Bash

pnpm dlx shadcn@latest add @spaceui/primitives-autocomplete

pnpm dlx shadcn@latest add @spaceui/primitives-autocomplete

Usage

Code

import {
  Autocomplete,
  AutocompleteEmpty,
  AutocompleteInput,
  AutocompleteItem,
  AutocompleteList,
  AutocompletePopup,
} from '@/components/ui/autocomplete'

const items = [
  { value: "apple", label: "Apple" },
  { value: "banana", label: "Banana" },
  { value: "orange", label: "Orange" },
  { value: "grape", label: "Grape" },
]

<Autocomplete items={items}>
  <AutocompleteInput placeholder="Search..." />
  <AutocompletePopup>
    <AutocompleteEmpty>No results found.</AutocompleteEmpty>
    <AutocompleteList>
      {(item) => <AutocompleteItem key={item.value} value={item}>{item.label}</AutocompleteItem>}
    </AutocompleteList>
  </AutocompletePopup>
</Autocomplete>

Features

Sizes

Autocomplete inputs in sm, default, and lg sizes.

API Reference

Autocomplete

The root autocomplete component. Manages the autocomplete state and provides context to child components.

Prop	Type	Description
`items`	readonly unknown[]	The array of items to display in the autocomplete
`open`	boolean	Controls whether the popup is open
`...props`	React.ComponentProps<typeof Autocomplete>	All Base UI Autocomplete props are supported

AutocompleteInput

The input field component with extended features for size variants and addon support.

Prop	Type	Default	Description
`size`	sm\|default\|lg	default	The size variant of the input field
`startAddon`	React.ReactNode	-	Element to display at the start (left side) of the input, such as an icon
`showTrigger`	boolean	false	Whether to display a trigger button (chevron icon) on the right side of the input
`showClear`	boolean	false	Whether to display a clear button (X icon) on the right side of the input when there is a value
`triggerProps`	Autocomplete.Trigger.Props	-	Props forwarded to the internal trigger button, useful for overriding `aria-label`
`clearProps`	Autocomplete.Clear.Props	-	Props forwarded to the internal clear button, useful for overriding `aria-label`
`className`	string	-	Additional CSS classes to apply to the component
`...props`	Base UI Autocomplete Input props	-	All standard autocomplete input attributes are supported

AutocompletePopup

The popup container that displays the autocomplete suggestions.

Prop	Type	Default	Description
`side`	top\|bottom\|left\|right	bottom	Preferred edge to position the popup relative to the trigger/input
`sideOffset`	number	4	Distance from the trigger in pixels
`align`	start\|center\|end	center	Alignment relative to the trigger along the cross-axis
`alignOffset`	number	0	Distance in pixels to shift the popup along the alignment axis
`anchor`	Element\|null\|React.RefObject<Element>	-	Custom anchor element or ref to anchor the popup against
`portalProps`	Autocomplete.Portal.Props	-	Props forwarded to the internal portal (`keepMounted`, `container`, etc.); see Base UI Combobox portal API (autocomplete reuses it)
`className`	string	-	Additional CSS classes to apply to the component
`...props`	Base UI Autocomplete Popup props	-	All standard autocomplete popup attributes are supported

AutocompleteList

A scrollable container for autocomplete items.

Prop	Type	Description
`className`	string	Additional CSS classes to apply to the component
`...props`	Base UI Autocomplete List props	All standard autocomplete list attributes are supported

AutocompleteItem

An individual selectable autocomplete item.

Prop	Type	Description
`value`	unknown	The value of the item
`className`	string	Additional CSS classes to apply to the component
`...props`	Base UI Autocomplete Item props	All standard autocomplete item attributes are supported

AutocompleteEmpty

Displays a message when no results are found.

Prop	Type	Description
`className`	string	Additional CSS classes to apply to the component
`...props`	Base UI Autocomplete Empty props	All standard autocomplete empty attributes are supported

AutocompleteGroup

Groups related autocomplete items together.

Prop	Type	Description
`items`	readonly unknown[]	The array of items in this group
`className`	string	Additional CSS classes to apply to the component
`...props`	Base UI Autocomplete Group props	All standard autocomplete group attributes are supported

AutocompleteGroupLabel

Displays a label for an autocomplete group.

Prop	Type	Description
`className`	string	Additional CSS classes to apply to the component
`...props`	Base UI Autocomplete Group Label props	All standard autocomplete group label attributes are supported

AutocompleteCollection

Used to wrap items within a group for rendering.

Prop	Type	Description
`...props`	Base UI Autocomplete Collection props	All standard autocomplete collection attributes are supported

Examples

Large autocomplete

Autocomplete with label

Fruits

Autocomplete autofilling the input with the highlighted item

Autocomplete auto highlighting the first option

Autocomplete with clear button

Autocomplete with trigger and clear buttons

Autocomplete with grouped items

Autocomplete with limited number of results

Autocomplete with async items loading

Autocomplete form

Pill-shaped autocomplete

Address autocomplete with Google Maps Places API