Autocomplete

A text input that suggests matching options as you type.

Usage

import {
  Autocomplete,
  AutocompleteInput,
  AutocompleteContent,
  AutocompleteEmpty,
  AutocompleteList,
  AutocompleteItem,
} from '@appica/ui-react/autocomplete'

const frameworks = ['Next.js', 'Remix', 'Astro', 'Nuxt.js', 'SvelteKit', 'SolidStart']

<Autocomplete items={frameworks}>
  <AutocompleteInput placeholder="Search a framework" />
  <AutocompleteContent>
    <AutocompleteEmpty>No frameworks found.</AutocompleteEmpty>
    <AutocompleteList>
      {(item) => (
        <AutocompleteItem key={item} value={item}>
          {item}
        </AutocompleteItem>
      )}
    </AutocompleteList>
  </AutocompleteContent>
</Autocomplete>

Autocomplete is a compound component. The root holds the data (items) and shared options (size, variant, clearable, icon); the parts compose the input and the filtered popup:

AutocompleteInput — the text field, styled like Input. Add a clear button with clearable and a dropdown chevron with icon (both on the root, both off by default).
AutocompleteContent — the portalled, auto-positioned popup. Accepts the shared floating props (side, align, sideOffset, …).
AutocompleteList — the scrollable list. Pass a render function to map over the filtered items, or static AutocompleteItems.
AutocompleteItem — one option; its value is what selection reports.
AutocompleteEmpty — shown only when the filter matches nothing.

Examples

Variants

variant switches the input appearance between a bordered outline (default) and a filled soft field.

'use client'

import {
  Autocomplete,
  AutocompleteInput,
  AutocompleteContent,
  AutocompleteEmpty,
  AutocompleteList,
  AutocompleteItem,
} from '@appica/ui-react/autocomplete'

const frameworks = ['Next.js', 'Remix', 'Astro', 'Nuxt.js', 'SvelteKit', 'SolidStart', 'Gatsby', 'Vite']
const variants = ['outline', 'soft'] as const

export default function AutocompleteVariants() {
  return (
    <div className="flex w-full max-w-70 flex-col gap-4">
      {variants.map((variant) => (
        <div key={variant}>
          <Autocomplete items={frameworks} variant={variant}>
            <AutocompleteInput placeholder="Search a framework" aria-label={`Search (${variant})`} />
            <AutocompleteContent>
              <AutocompleteEmpty>No frameworks found.</AutocompleteEmpty>
              <AutocompleteList>
                {(item: string) => (
                  <AutocompleteItem key={item} value={item}>
                    {item}
                  </AutocompleteItem>
                )}
              </AutocompleteList>
            </AutocompleteContent>
          </Autocomplete>
        </div>
      ))}
    </div>
  )
}

Sizes

size on the root scales the input, popup radius, and items together.

'use client'

import {
  Autocomplete,
  AutocompleteInput,
  AutocompleteContent,
  AutocompleteEmpty,
  AutocompleteList,
  AutocompleteItem,
} from '@appica/ui-react/autocomplete'

const frameworks = ['Next.js', 'Remix', 'Astro', 'Nuxt.js', 'SvelteKit', 'SolidStart', 'Gatsby', 'Vite']
const sizes = ['sm', 'md', 'lg'] as const

export default function AutocompleteSizes() {
  return (
    <div className="flex w-full max-w-70 flex-col gap-4">
      {sizes.map((size) => (
        <div key={size}>
          <Autocomplete items={frameworks} size={size}>
            <AutocompleteInput placeholder="Search a framework" aria-label={`Search (${size})`} />
            <AutocompleteContent>
              <AutocompleteEmpty>No frameworks found.</AutocompleteEmpty>
              <AutocompleteList>
                {(item: string) => (
                  <AutocompleteItem key={item} value={item}>
                    {item}
                  </AutocompleteItem>
                )}
              </AutocompleteList>
            </AutocompleteContent>
          </Autocomplete>
        </div>
      ))}
    </div>
  )
}

Clearable & chevron

Set clearable to add a clear (✕) button once there's a value, and icon to add a chevron that toggles the popup. Both render inside the input and are off by default.

'use client'

import {
  Autocomplete,
  AutocompleteInput,
  AutocompleteContent,
  AutocompleteEmpty,
  AutocompleteList,
  AutocompleteItem,
} from '@appica/ui-react/autocomplete'

const frameworks = ['Next.js', 'Remix', 'Astro', 'Nuxt.js', 'SvelteKit', 'SolidStart', 'Gatsby', 'Vite']

export default function AutocompleteClearable() {
  return (
    <div className="w-full max-w-70">
      <Autocomplete items={frameworks} defaultValue="Next.js" clearable icon>
        <AutocompleteInput placeholder="Search a framework" aria-label="Search a framework" />
        <AutocompleteContent>
          <AutocompleteEmpty>No frameworks found.</AutocompleteEmpty>
          <AutocompleteList>
            {(item: string) => (
              <AutocompleteItem key={item} value={item}>
                {item}
              </AutocompleteItem>
            )}
          </AutocompleteList>
        </AutocompleteContent>
      </Autocomplete>
    </div>
  )
}

Items with icons

Items can render any content. Mark a leading icon with data-icon="start" so it gets the same inner spacing as in Button. When items are objects rather than strings, give the root an itemToStringValue so the filter and input know how to read each one. Here the selected command's icon is mirrored back into the input via AutocompleteInput's startSlot.

'use client'

import * as React from 'react'
import {
  Autocomplete,
  AutocompleteInput,
  AutocompleteContent,
  AutocompleteEmpty,
  AutocompleteList,
  AutocompleteItem,
} from '@appica/ui-react/autocomplete'
import { LayoutDashboard, User, Settings, CreditCard, Bell, Mail } from '@appica/icons-react'

interface Command {
  label: string
  icon: React.ElementType
}

const commands: Command[] = [
  { label: 'Dashboard', icon: LayoutDashboard },
  { label: 'Profile', icon: User },
  { label: 'Settings', icon: Settings },
  { label: 'Billing', icon: CreditCard },
  { label: 'Notifications', icon: Bell },
  { label: 'Messages', icon: Mail },
]

export default function AutocompleteWithIcons() {
  const [value, setValue] = React.useState('')
  const selected = commands.find((command) => command.label === value)

  return (
    <div className="w-full max-w-70">
      <Autocomplete
        items={commands}
        value={value}
        onValueChange={(v: string) => setValue(v)}
        itemToStringValue={(item) => (item as Command).label}
        clearable
        icon
      >
        <AutocompleteInput
          placeholder="Search commands"
          aria-label="Search commands"
          startSlot={selected ? <selected.icon aria-hidden /> : null}
        />
        <AutocompleteContent>
          <AutocompleteEmpty>No commands found.</AutocompleteEmpty>
          <AutocompleteList>
            {(command: Command) => (
              <AutocompleteItem key={command.label} value={command}>
                <command.icon data-icon="start" />
                {command.label}
              </AutocompleteItem>
            )}
          </AutocompleteList>
        </AutocompleteContent>
      </Autocomplete>
    </div>
  )
}

Country search

The same object-item pattern with country flags — a typical country picker. Each item renders a flag before the name, and the selected country's flag is mirrored into the input through startSlot.

'use client'

import * as React from 'react'
import {
  Autocomplete,
  AutocompleteInput,
  AutocompleteContent,
  AutocompleteEmpty,
  AutocompleteList,
  AutocompleteItem,
} from '@appica/ui-react/autocomplete'
import { CountryFlagRounded } from '@appica/country-flags-react'

interface Country {
  code: string
  name: string
}

const countries: Country[] = [
  { code: 'au', name: 'Australia' },
  { code: 'br', name: 'Brazil' },
  { code: 'ca', name: 'Canada' },
  { code: 'fr', name: 'France' },
  { code: 'de', name: 'Germany' },
  { code: 'it', name: 'Italy' },
  { code: 'jp', name: 'Japan' },
  { code: 'es', name: 'Spain' },
  { code: 'gb', name: 'United Kingdom' },
  { code: 'us', name: 'United States' },
]

export default function AutocompleteCountrySearch() {
  const [value, setValue] = React.useState('')
  const selected = countries.find((country) => country.name === value)

  return (
    <div className="w-full max-w-70">
      <Autocomplete
        items={countries}
        value={value}
        onValueChange={(v: string) => setValue(v)}
        itemToStringValue={(item) => (item as Country).name}
        clearable
        icon
      >
        <AutocompleteInput
          placeholder="Search a country"
          aria-label="Search a country"
          startSlot={selected ? <CountryFlagRounded code={selected.code} aria-hidden /> : null}
        />
        <AutocompleteContent>
          <AutocompleteEmpty>No countries found.</AutocompleteEmpty>
          <AutocompleteList>
            {(country: Country) => (
              <AutocompleteItem key={country.code} value={country}>
                <CountryFlagRounded code={country.code} data-icon="start" aria-hidden />
                {country.name}
              </AutocompleteItem>
            )}
          </AutocompleteList>
        </AutocompleteContent>
      </Autocomplete>
    </div>
  )
}

Grouped options

Pass a grouped items array — { value, items }[] — and render each group with AutocompleteGroup + AutocompleteLabel + AutocompleteCollection. The outer render function iterates groups; AutocompleteCollection renders the items inside each.

'use client'

import {
  Autocomplete,
  AutocompleteInput,
  AutocompleteContent,
  AutocompleteEmpty,
  AutocompleteList,
  AutocompleteItem,
  AutocompleteGroup,
  AutocompleteLabel,
  AutocompleteCollection,
} from '@appica/ui-react/autocomplete'

interface ProduceGroup {
  value: string
  items: string[]
}

const groups: ProduceGroup[] = [
  { value: 'Fruits', items: ['Apple', 'Banana', 'Cherry', 'Grapefruit', 'Mango', 'Orange', 'Strawberry'] },
  { value: 'Vegetables', items: ['Broccoli', 'Carrot', 'Cucumber', 'Lettuce', 'Potato', 'Spinach', 'Tomato'] },
  { value: 'Herbs', items: ['Basil', 'Mint', 'Oregano', 'Parsley', 'Rosemary', 'Thyme'] },
]

export default function AutocompleteGrouped() {
  return (
    <div className="w-full max-w-70">
      <Autocomplete items={groups}>
        <AutocompleteInput placeholder="Search produce" aria-label="Search produce" />
        <AutocompleteContent>
          <AutocompleteEmpty>No produce found.</AutocompleteEmpty>
          <AutocompleteList>
            {(group: ProduceGroup) => (
              <AutocompleteGroup key={group.value} items={group.items}>
                <AutocompleteLabel>{group.value}</AutocompleteLabel>
                <AutocompleteCollection>
                  {(item: string) => (
                    <AutocompleteItem key={item} value={item}>
                      {item}
                    </AutocompleteItem>
                  )}
                </AutocompleteCollection>
              </AutocompleteGroup>
            )}
          </AutocompleteList>
        </AutocompleteContent>
      </Autocomplete>
    </div>
  )
}

Grid layout

Set grid on the root to lay options out in a grid (arrow keys move in two dimensions). AutocompleteList's cols controls how many items per row.

'use client'

import {
  Autocomplete,
  AutocompleteInput,
  AutocompleteContent,
  AutocompleteEmpty,
  AutocompleteList,
  AutocompleteItem,
} from '@appica/ui-react/autocomplete'

const tags = ['React', 'Vue', 'Svelte', 'Angular', 'Solid', 'Qwik', 'Preact', 'Lit']

export default function AutocompleteGrid() {
  return (
    <div className="w-full max-w-70">
      <Autocomplete items={tags} grid icon>
        <AutocompleteInput placeholder="Search a library" aria-label="Search a library" />
        <AutocompleteContent>
          <AutocompleteEmpty>No libraries found.</AutocompleteEmpty>
          <AutocompleteList cols={2}>
            {(item: string) => (
              <AutocompleteItem key={item} value={item} className="flex-1">
                {item}
              </AutocompleteItem>
            )}
          </AutocompleteList>
        </AutocompleteContent>
      </Autocomplete>
    </div>
  )
}

Controlled

Drive the input value yourself with value + onValueChange — useful for syncing with form state or reacting to every keystroke.

Current value: —

'use client'

import * as React from 'react'
import {
  Autocomplete,
  AutocompleteInput,
  AutocompleteContent,
  AutocompleteEmpty,
  AutocompleteList,
  AutocompleteItem,
} from '@appica/ui-react/autocomplete'

const frameworks = ['Next.js', 'Remix', 'Astro', 'Nuxt.js', 'SvelteKit', 'SolidStart', 'Gatsby', 'Vite']

export default function AutocompleteControlled() {
  const [value, setValue] = React.useState('')

  return (
    <div className="flex w-full max-w-70 flex-col gap-3">
      <Autocomplete items={frameworks} value={value} onValueChange={(v: string) => setValue(v)} clearable>
        <AutocompleteInput placeholder="Search a framework" aria-label="Search a framework" />
        <AutocompleteContent>
          <AutocompleteEmpty>No frameworks found.</AutocompleteEmpty>
          <AutocompleteList>
            {(item: string) => (
              <AutocompleteItem key={item} value={item}>
                {item}
              </AutocompleteItem>
            )}
          </AutocompleteList>
        </AutocompleteContent>
      </Autocomplete>
      <p className="text-foreground-muted text-sm">
        Current value: <span className="text-foreground font-medium">{value || '—'}</span>
      </p>
    </div>
  )
}

RTL

Every Appica UI component supports right-to-left layouts out of the box. Set the dir attribute on a container (commonly your <html> element) so CSS logical properties resolve correctly, and wrap your tree in DirectionProvider so direction-aware behavior — roving focus, popup placement, and the like — follows the same direction.

import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}

For setup details and caveats, see the RTL guide.

API reference

Autocomplete wraps Base UI's Autocomplete. Each part forwards every remaining prop to the matching Base UI primitive, so anything it accepts works here — the tables below list the Appica additions and the most common props. See the Base UI docs for the complete API.

Autocomplete

The root. Holds the data and the shared styling/behavior options; renders no DOM of its own.

Prop	Type	Default	Description
`items`	`readonly T[] \| { value, items }[]`	—	The data to filter. A flat array, or `{ value, items }` objects for grouped options.
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Input height, popup radius, and item sizing.
`variant`	`'outline' \| 'soft'`	`'outline'`	Input appearance — bordered or filled.
`clearable`	`boolean`	`false`	Render a clear button inside the input when a value is present.
`icon`	`boolean`	`false`	Render a chevron button that toggles the popup.
`grid`	`boolean`	`false`	Lay options out as a navigable grid instead of a list.
`value`	`string`	—	Controlled input value. Pair with `onValueChange`.
`defaultValue`	`string`	—	Uncontrolled initial input value.
`onValueChange`	`(value, details) => void`	—	Fires as the value changes (typing, selection, clear).
`itemToStringValue`	`(item: T) => string`	—	Required for object items: how the filter and input read each one.
`mode`	`'list' \| 'inline' \| 'both' \| 'none'`	`'list'`	Inline modes autofill the input with the highlighted item while navigating.

AutocompleteInput

The text field. Renders Base UI's Input inside an InputGroup, styled like Input.

Prop	Type	Default	Description
`startSlot`	`ReactNode`	—	Adornment rendered before the field, inside the input frame.
`endSlot`	`ReactNode`	—	Adornment rendered after the field, inside the input frame.
`placeholder`	`string`	`' '`	Placeholder text.
`disabled`	`boolean`	`false`	Disables the field and the clear/chevron buttons.
`className`	`string`	—	Extra classes on the input group, merged via `tailwind-merge`.

Also forwards every native <input> prop (onChange, name, aria-*, ref, …).

AutocompleteContent

The portalled, auto-positioned popup wrapping the list. Accepts the shared floating props.

Prop	Type	Default	Description
`side`	`'top' \| 'right' \| 'bottom' \| 'left'`	`'bottom'`	Preferred side of the input to open on.
`align`	`'start' \| 'center' \| 'end'`	—	Alignment along that side.
`sideOffset`	`number`	`6`	Gap between the input and the popup.
`alignOffset`	`number`	—	Shift along the alignment axis.
`container`	`HTMLElement \| ref \| null`	—	Portal target — render the popup into a different node.
`keepMounted`	`boolean`	`false`	Keep the popup mounted in the DOM while closed.
`positionerProps`	`object`	—	Escape hatch for the positioner element (`style`, `render`, …).
`portalProps`	`object`	—	Escape hatch for the portal element (`style`, `render`, …).
`className`	`string`	—	Extra classes on the popup.

AutocompleteList

The scrollable list container.

Prop	Type	Default	Description
`cols`	`number`	—	Items per row in grid mode (defaults to 2 when `grid` is set).
`children`	`ReactNode \| (item, index) => ReactNode`	—	A render function over the filtered items, or static `AutocompleteItem`s.

AutocompleteItem

One option in the list.

Prop	Type	Default	Description
`value`	`T`	—	The item this option represents; reported on selection.
`className`	`string`	—	Extra classes (e.g. `flex-1` to fill a grid cell).

AutocompleteEmpty

Shown only when the filter matches nothing — otherwise it renders nothing.

Prop	Type	Default	Description
`children`	`ReactNode`	—	The empty-state message.
`className`	`string`	—	Extra classes, merged via `tailwind-merge`.

AutocompleteStatus

A persistent row that stays mounted (e.g. a loading or count message), unlike AutocompleteEmpty.

Prop	Type	Default	Description
`children`	`ReactNode`	—	The status message.
`className`	`string`	—	Extra classes, merged via `tailwind-merge`.

AutocompleteGroup

Wraps one labelled section of a grouped list.

Prop	Type	Default	Description
`items`	`readonly T[]`	—	The group's items, so the inner `AutocompleteCollection` can map them.
`className`	`string`	—	Extra classes, merged via `tailwind-merge`.

AutocompleteLabel

The visible label for an AutocompleteGroup.

Prop	Type	Default	Description
`children`	`ReactNode`	—	The label text.
`className`	`string`	—	Extra classes, merged via `tailwind-merge`.

AutocompleteCollection

Renders the items inside an AutocompleteGroup.

Prop	Type	Default	Description
`children`	`(item, index) => ReactNode`	—	Render function for each item — `(item) => <AutocompleteItem … />`.

AutocompleteSeparator

A thin divider between sections.

Prop	Type	Default	Description
`className`	`string`	—	Extra classes, merged via `tailwind-merge`.

AutocompleteTrigger

A standalone button that opens the popup (e.g. a tag picker that isn't a text field).

Prop	Type	Default	Description
`render`	`ReactElement \| ((props, state) => ReactElement)`	—	Compose the trigger with another element.
`className`	`string`	—	Extra classes, merged via `tailwind-merge`.

Also forwards every native <button> prop (onClick, aria-*, ref, …).

AutocompleteValue

Renders the current value for read-only display.

Prop	Type	Default	Description
`children`	`ReactNode \| (value) => ReactNode`	—	Static content, or a render function of the value.

Accessibility

The input has role="combobox"; the popup is a listbox (or grid when grid is set) and items are option/gridcell. Selection and active state are wired through aria-activedescendant.
↑/↓ move the highlight, Enter selects, Escape closes the popup, and typing filters the list.
The clear and chevron buttons have aria-labels (Clear selection, Toggle popup) and become disabled when the input is disabled.
Always give AutocompleteInput a visible label or an aria-label.
Popup enter/exit transitions are wrapped so they're skipped when the user prefers reduced motion.

Actions & Inputs

Data Display

Decoration & Effects

Layout

Menus

Navigation

Overlays

Status & Feedback

Autocomplete

Usage

Examples

Variants

Sizes

Clearable & chevron

Items with icons

Country search

Grouped options

Grid layout

Controlled

RTL

API reference

Autocomplete

AutocompleteInput

AutocompleteContent

AutocompleteList

AutocompleteItem

AutocompleteEmpty

AutocompleteStatus

AutocompleteGroup

AutocompleteLabel

AutocompleteCollection

AutocompleteSeparator

AutocompleteTrigger

AutocompleteValue

Accessibility