# Autocomplete

An input that suggests options as you type.

- Category: Forms
- Page: https://wunderui.com/components/autocomplete
- Tier: Free

## Install

```bash
npx wunderui-cli add autocomplete
```

## Import

```tsx
import { Autocomplete, AutocompleteEmpty, AutocompleteInput, AutocompleteInputGroup, AutocompleteItem, AutocompleteList, AutocompletePopup, AutocompletePortal } from "@/components/ui/autocomplete"
```

## Minimal usage

Then use it:

```tsx
import {
  Autocomplete,
  AutocompleteEmpty,
  AutocompleteInput,
  AutocompleteInputGroup,
  AutocompleteItem,
  AutocompleteList,
  AutocompletePopup,
} from "@/components/ui/autocomplete"

const cities = ["Berlin", "Copenhagen", "Lisbon", "Madrid", "Vienna"]

export function CityField() {
  return (
    <Autocomplete items={cities}>
      <AutocompleteInputGroup>
        <AutocompleteInput aria-label="City" placeholder="Search cities" />
      </AutocompleteInputGroup>
      <AutocompletePopup>
        <AutocompleteEmpty>No cities match.</AutocompleteEmpty>
        <AutocompleteList>
          {(city) => (
            <AutocompleteItem key={city} value={city}>
              {city}
            </AutocompleteItem>
          )}
        </AutocompleteList>
      </AutocompletePopup>
    </Autocomplete>
  )
}
```

Expected result: You should see a text field with the placeholder Search cities. Type li and the list keeps Berlin and Lisbon; press Arrow Down and Enter and the field fills with Berlin.

## Usage

```tsx
import {
  Autocomplete,
  AutocompleteEmpty,
  AutocompleteInput,
  AutocompleteInputGroup,
  AutocompleteItem,
  AutocompleteList,
  AutocompletePopup,
} from "@/components/ui/autocomplete"
import { Label } from "@/components/ui/label"

const cities = ["Berlin", "Copenhagen", "Lisbon", "Madrid", "Vienna"]

export function Example() {
  return (
    <div className="flex flex-col gap-2">
      <Label htmlFor="city">City</Label>
      <Autocomplete items={cities}>
        <AutocompleteInputGroup>
          <AutocompleteInput id="city" placeholder="Search cities" />
        </AutocompleteInputGroup>
        <AutocompletePopup>
          <AutocompleteEmpty>No cities match.</AutocompleteEmpty>
          <AutocompleteList>
            {(city) => (
              <AutocompleteItem key={city} value={city}>
                {city}
              </AutocompleteItem>
            )}
          </AutocompleteList>
        </AutocompletePopup>
      </Autocomplete>
    </div>
  )
}
```

## When to use

### Use Autocomplete for

- Free text with help, such as a city, a search term or a label that may be new
- A field where any value is valid and the suggestions only save typing
- Search boxes whose suggestions come from your own data

### Use something else

- [Combobox](https://wunderui.com/components/combobox) for the answer must be one of the entries
- [Select](https://wunderui.com/components/select) for a short, fixed list, with no typing
- [Dropdown Menu](https://wunderui.com/components/dropdown-menu) for a list of actions, not a value for a field

## Keyboard

The input is a native text field, so the browser provides focus, typing and the caret. The list is not in the tab order: arrow keys reach it from the input, and focus stays there.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus into the field and out of it. Leaving closes the list and keeps the text. |
| `A–Z` | Typing opens the list and keeps the suggestions that match. Clearing the field closes it again. |
| `ArrowDown` or `ArrowUp` | Opens the list if it is closed, then moves the highlight to the next or previous suggestion. At the end of the list focus goes back to the text with nothing highlighted, and one more press starts at the other end. |
| `Enter` | Takes the highlighted suggestion: it fills the field and closes the list. With nothing highlighted Enter does what it does in any text field, so a form around the field is submitted. |
| `Escape` | Closes the list. Pressed again, it clears the text. |

## Behavior

What the field does with text, matching, the list and motion.

- **Text, not a choice:** The value is the text in the field. Choosing a suggestion fills it with that text, text that matches nothing stays as typed, and you should check it on submit when only some values are valid.
- **Opening:** The list opens when the person types or presses Arrow Down or Arrow Up, and closes when the field is empty. It can also open on click, and the field keeps focus while it is open.
- **Matching:** A suggestion matches when it contains the typed text, ignoring case and accents. You can replace the rule, highlight the first match so Enter takes it, and cap the number of suggestions.
- **Objects as items:** Items can be objects. Give each item the object as its value, and the root a function that turns it into the field's text.
- **No match:** The empty line shows in the list when nothing matches and is hidden while it has no content. Give it a sentence so a list without matches never looks broken.
- **Position and size:** The list opens below the field, 4 px away and as wide as the field (12 rem at least). It flips above when there is no room below and scrolls when it is taller than the room left.
- **Highlight:** The pointer and the keyboard share one highlight, drawn with the page fill of a hovered row. Moving the pointer over a row highlights it; you can switch that off.
- **Invalid and disabled:** Mark the input invalid to turn the border and focus ring red, and say why in a line under the field linked with aria-describedby. Disabled dims the field to 40 % and ignores pointer and keyboard.
- **Previews in these docs:** The list is portalled to the end of the document and floats over the page. The previews here draw it inside the card so it stays contained, and show it only while the whole card is on screen.
- **Motion:** The list appears and disappears at once. Nothing else moves: the border and focus ring change colour quickly.
- **Reduced motion:** There is no movement to remove, so reduced motion changes nothing. The colour change is a short fade and stays.

## Anatomy

- `Autocomplete`: The root. It holds the field's text, the items and the filter and renders nothing itself; the value is the text in the input, not a chosen item.
- `AutocompleteInputGroup`: The bordered frame around the input, 36 px high with an 8 px corner. It draws the border and focus ring, dims when disabled and turns red when invalid, so put an icon beside the input inside it.
- `AutocompleteInput`: The text input. Typing filters the suggestions, arrow keys move through them, Enter takes one and Escape closes the list; give it a visible label or an aria-label.
- `AutocompletePopup`: The suggestion panel. It brings its own portal and positioner, matches the field's width and scrolls when it runs out of room.
- `AutocompleteList`: Renders the items. Pass a render function as the child so the filtered list, not the full one, is mapped.
- `AutocompleteItem`: One suggestion, 32 px high for a single line, whose value fills the field when chosen. A row can hold an icon, or an avatar and a second line, and the highlighted row gets the page fill.
- `AutocompleteEmpty`: A centred line shown in place of the list when nothing matches. It is hidden while it has no content.
- `AutocompletePortal`: Moves the list to the end of the document. The popup already uses it; you only need it for a custom container.

## Best practices

### Do

- Give the input a visible label. The placeholder is a hint such as Search cities, not the name of the field.
- Always add an empty-state line with a sentence like No cities match, so a list without matches never looks broken.
- Control the value with state when the text drives something else, such as a server search. The value is the text of the field, never an item object.
- Keep the suggestions few, five to eight, and one line each. Cap a long list with a limit; people pick by reading, so rows with several lines or controls slow them down.

### Don't

- Don't treat the value as validated. Text that matches no suggestion still ends up in the value, so check it on submit or use a Combobox.
- Don't use it for a choice that must come from the list. A Combobox keeps the field on a value of the list and tells people when nothing matches.
- Don't use it as a menu of actions. Suggestions fill a field; actions belong in a Dropdown Menu.

## API reference

### Autocomplete

| Prop | Type | Default | Description |
|---|---|---|---|
| actionsRef | React.RefObject<AutocompleteRootActions \| null> |  | A ref to imperative actions. - `unmount`: Manually unmounts the autocomplete. Call this after any externally controlled closing animation finishes. |
| autoHighlight | boolean \| 'always' | false | Highlights the first matching suggestion so Enter takes it. `true` does it after the person types; `"always"` does it whenever the list opens. |
| children | React.ReactNode |  |  |
| defaultOpen | boolean | false | Whether the list starts open when you do not control it. |
| defaultValue | AriaCombobox.Props<React.ComponentProps<'input'>['defaultValue'], 'none'>['defaultInputValue'] |  | The text the field starts with when you do not control it. |
| disabled | boolean | false | Disables the field: it dims to 40 % and ignores the pointer and the keyboard. |
| filter | AriaCombobox.Props<ItemValue, 'none'>['filter'] |  | Replaces the matching rule. It receives an item, the typed text and the function that turns an item into text, and returns whether the item stays in the list. |
| filteredItems | readonly ItemValue[] \| readonly Group<ItemValue>[] |  | Filtered items to display in the list. When provided, the list uses these items instead of filtering the `items` prop internally. When `items` is also provided, this array must preserve its flat or grouped structure. Nullish entries are no… |
| form | string |  | Identifies the form that owns the internal input. Useful when the autocomplete is rendered outside the form. |
| grid | boolean | false | Whether list items are presented in a grid layout. When enabled, arrow keys navigate across rows and columns inferred from DOM rows. |
| highlightItemOnHover | boolean | true | Whether moving the pointer over items should highlight them. Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state. |
| id | string |  | The id of the component. |
| inline | boolean | false | Whether the list is rendered inline without using the component's own popup. Specify `open` unconditionally in conjunction with this prop so the list is considered visible: `<Autocomplete.Root inline open>` |
| inputRef | React.Ref<HTMLInputElement> |  | A ref to the hidden input element. |
| items | readonly ItemValue[] \| readonly Group<ItemValue>[] |  | The suggestions: a flat array of strings or objects. The list filters them as the person types; the render function of `AutocompleteList` receives the ones that match. |
| itemToStringValue | ((itemValue: ItemValue) => string) |  | Turns an object item into the text of the field and of the submitted form. Needed when the items are objects. |
| keepHighlight | boolean | false | Whether the highlighted item should be preserved when the pointer leaves the list. |
| limit | number | -1 | The most suggestions the list shows. `-1`, the default, shows every match. |
| locale | Intl.LocalesArgument |  | The locale to use for string comparison. Defaults to the user's runtime locale. |
| loopFocus | boolean | true | Whether to loop keyboard focus back to the input when the end of the list is reached while using the arrow keys. The first item can then be reached by pressing <kbd>ArrowDown</kbd> again from the input, or the last item can be reached by p… |
| modal | boolean | false | Determines if the popup enters a modal state when open. - `true`: user interaction is limited to the popup: document page scroll is locked and pointer interactions on outside elements are disabled. - `false`: user interaction with the rest… |
| mode | 'list' \| 'both' \| 'inline' \| 'none' | 'list' | `list`, the default, filters the suggestions and leaves the text alone. `both` also completes the text inline, `inline` only completes inline, and `none` shows the list without filtering. |
| name | string |  | The name the text is submitted under in a form. |
| onItemHighlighted | ((highlightedValue: ItemValue \| undefined, eventDetails: AutocompleteRootHighlightEventDetails) => 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 b… |
| onOpenChange | ((open: boolean, eventDetails: AutocompleteRootChangeEventDetails) => void) |  | Called when the list opens or closes, with the reason, such as typing, a key press, an outside press or choosing a suggestion. |
| onOpenChangeComplete | ((open: boolean) => void) |  | Event handler called after any animations complete when the popup is opened or closed. |
| onValueChange | ((value: string, eventDetails: AutocompleteRootChangeEventDetails) => void) |  | Called with the new text each time the person types, clears the field or takes a suggestion. |
| open | boolean |  | Whether the list is open, when you control it. Pair it with `onOpenChange`. |
| openOnInputClick | boolean | false | Opens the list when the field is clicked. Off by default: the list opens on typing and on the arrow keys. |
| readOnly | boolean | false | Keeps the text but stops people from choosing a suggestion. |
| required | boolean | false | Marks the field as required for the form it belongs to. |
| submitOnItemClick | AriaCombobox.Props<ItemValue, 'none'>['submitOnItemClick'] | false | Whether clicking an item should submit the autocomplete's owning form. By default, clicking an item via a pointer or <kbd>Enter</kbd> key does not submit the owning form. Useful when the autocomplete is used as a single-field form search i… |
| value | AriaCombobox.Props<React.ComponentProps<'input'>['value'], 'none'>['inputValue'] |  | The text in the field, as a string. It is a controlled value: update it in `onValueChange`. |
| virtualized | boolean | false | Whether the items are being externally virtualized. |

### AutocompleteEmpty

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | Extra classes for the line shown when nothing matches. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | 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) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.HTMLAttributes attributes.

### AutocompleteInput

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | Extra classes for the input inside the frame. |
| disabled | boolean | false | Disables this input only. Prefer `disabled` on the root, which also dims the frame. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | 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) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.InputHTMLAttributes attributes.

### AutocompleteInputGroup

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | Extra classes for the frame, for example `w-72` for a fixed width or `h-(--field-lg)` for the large height. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | 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) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.HTMLAttributes attributes.

### AutocompleteItem

| Prop | Type | Default | Description |
|---|---|---|---|
| children | React.ReactNode |  |  |
| className | string \| ((state: State) => string \| undefined) |  | Extra classes for the row, for example `gap-3` for a row with an avatar. |
| disabled | boolean | false | Stops the row from being highlighted or chosen. |
| index | number |  | The index of the item in the list. Improves performance when specified by avoiding the need to calculate the index automatically from the DOM. |
| nativeButton | boolean | false | 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. |
| onClick | BaseUIComponentProps<'div', AutocompleteItemState>['onClick'] |  | Called when the row is clicked or taken with Enter. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | 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) |  | Style applied to the element, or a function that returns a style object based on the component's state. |
| value | any | null | The item this row stands for, the same string or object as in `items`. It is what fills the field when the row is chosen. |

Also accepts React.HTMLAttributes attributes.

### AutocompleteList

| Prop | Type | Default | Description |
|---|---|---|---|
| children | React.ReactNode \| ((item: any, index: number) => React.ReactNode) |  | A render function, `(item, index) => <AutocompleteItem ... />`, that receives the items that match. |
| className | string \| ((state: State) => string \| undefined) |  | Extra classes for the list element inside the panel. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | 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) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.HTMLAttributes attributes.

### AutocompletePopup

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | Extra classes for the list panel, for example `min-w-64` to make it wider than the field. |
| finalFocus | boolean \| React.RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => void \| boolean \| HTMLElement \| null) |  | Where focus goes when the list closes. It stays in the input by default. |
| initialFocus | boolean \| React.RefObject<HTMLElement \| null> \| ((openType: InteractionType) => void \| boolean \| HTMLElement \| null) |  | Where focus goes when the list opens. It stays in the input by default, so people can keep typing. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | 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) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.HTMLAttributes attributes.

### AutocompletePortal

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | CSS class applied to the element, or a function that returns a class based on the component's state. |
| container | HTMLElement \| ShadowRoot \| React.RefObject<HTMLElement \| ShadowRoot \| null> \| null |  | The element the list is moved into. The end of the document by default. |
| keepMounted | boolean | false | Keeps the list in the DOM while it is closed. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | 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) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.HTMLAttributes attributes.

## Examples

### Content: text, an icon or a person

```tsx
import {
  Autocomplete,
  AutocompleteEmpty,
  AutocompleteInput,
  AutocompleteInputGroup,
  AutocompleteItem,
  AutocompleteList,
  AutocompletePopup,
} from "@/components/ui/autocomplete"
import { Label } from "@/components/ui/label"

const cities = ["Berlin", "Copenhagen", "Lisbon", "Madrid", "Vienna"]

export function Example() {
  return (
    <div className="flex flex-col gap-2">
      <Label htmlFor="city">City</Label>
      <Autocomplete items={cities}>
        <AutocompleteInputGroup>
          <AutocompleteInput id="city" placeholder="Search cities" />
        </AutocompleteInputGroup>
        <AutocompletePopup>
          <AutocompleteEmpty>No cities match.</AutocompleteEmpty>
          <AutocompleteList>
            {(city) => (
              <AutocompleteItem key={city} value={city}>
                {city}
              </AutocompleteItem>
            )}
          </AutocompleteList>
        </AutocompletePopup>
      </Autocomplete>
    </div>
  )
}
```

### Matching: contains, starts with and highlight first

```tsx
import {
  Autocomplete,
  AutocompleteEmpty,
  AutocompleteInput,
  AutocompleteInputGroup,
  AutocompleteItem,
  AutocompleteList,
  AutocompletePopup,
} from "@/components/ui/autocomplete"
import { Label } from "@/components/ui/label"

const cities = ["Berlin", "Copenhagen", "Lisbon", "Madrid", "Vienna"]

export function Example() {
  return (
    <div className="flex flex-col gap-2">
      <Label htmlFor="city">City</Label>
      <Autocomplete
        items={cities}
        defaultValue="li"
      >
        <AutocompleteInputGroup>
          <AutocompleteInput id="city" placeholder="Search cities" />
        </AutocompleteInputGroup>
        <AutocompletePopup>
          <AutocompleteEmpty>No cities match.</AutocompleteEmpty>
          <AutocompleteList>
            {(city) => (
              <AutocompleteItem key={city} value={city}>
                {city}
              </AutocompleteItem>
            )}
          </AutocompleteList>
        </AutocompletePopup>
      </Autocomplete>
    </div>
  )
}
```

### States: default, filled, invalid and disabled

```tsx
import {
  Autocomplete,
  AutocompleteEmpty,
  AutocompleteInput,
  AutocompleteInputGroup,
  AutocompleteItem,
  AutocompleteList,
  AutocompletePopup,
} from "@/components/ui/autocomplete"
import { Label } from "@/components/ui/label"

const cities = ["Berlin", "Copenhagen", "Lisbon", "Madrid", "Vienna"]

export function Example() {
  return (
    <div className="flex flex-col gap-2">
      <Label htmlFor="city">City</Label>
      <Autocomplete items={cities}>
        <AutocompleteInputGroup>
          <AutocompleteInput id="city" placeholder="Search cities" />
        </AutocompleteInputGroup>
        <AutocompletePopup>
          <AutocompleteEmpty>No cities match.</AutocompleteEmpty>
          <AutocompleteList>
            {(city) => (
              <AutocompleteItem key={city} value={city}>
                {city}
              </AutocompleteItem>
            )}
          </AutocompleteList>
        </AutocompletePopup>
      </Autocomplete>
    </div>
  )
}
```

## In context

### City in an address form

Suggestions help, they don't restrict: a city that isn't in the list is saved as typed. A Combobox would refuse it.

```tsx
import { useState } from "react"
import {
  Autocomplete,
  AutocompleteEmpty,
  AutocompleteInput,
  AutocompleteInputGroup,
  AutocompleteItem,
  AutocompleteList,
  AutocompletePopup,
} from "@/components/ui/autocomplete"
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"

const cities = ["Berlin", "Copenhagen", "Lisbon", "Madrid", "Vienna"]

export function AddressForm() {
  const [city, setCity] = useState("")

  return (
    <form className="flex flex-col gap-4">
      <div className="flex flex-col gap-2">
        <Label htmlFor="street">Street</Label>
        <Input id="street" placeholder="Rua Augusta 120" autoComplete="address-line1" />
      </div>
      <div className="flex flex-col gap-2">
        <Label htmlFor="city">City</Label>
        <Autocomplete items={cities} value={city} onValueChange={setCity}>
          <AutocompleteInputGroup>
            <AutocompleteInput id="city" placeholder="Search cities" autoComplete="address-level2" />
          </AutocompleteInputGroup>
          <AutocompletePopup>
            <AutocompleteEmpty>No cities match.</AutocompleteEmpty>
            <AutocompleteList>
              {(item) => (
                <AutocompleteItem key={item} value={item}>
                  {item}
                </AutocompleteItem>
              )}
            </AutocompleteList>
          </AutocompletePopup>
        </Autocomplete>
        <p className="text-xs text-text-tertiary">Suggestions only. Any other city is fine too.</p>
      </div>
    </form>
  )
}
```

### Assign a task to a person

Each suggestion shows an avatar, a name and a role. Pick a name and the task card updates.

```tsx
import { useState } from "react"
import {
  Autocomplete,
  AutocompleteEmpty,
  AutocompleteInput,
  AutocompleteInputGroup,
  AutocompleteItem,
  AutocompleteList,
  AutocompletePopup,
} from "@/components/ui/autocomplete"
import { Avatar, AvatarFallback } from "@/components/ui/avatar"
import { Label } from "@/components/ui/label"

const people = [
  { name: "Nora Lindgren", role: "Design lead", initials: "NL" },
  { name: "Daniel Okafor", role: "Engineering", initials: "DO" },
  { name: "Priya Raman", role: "Product", initials: "PR" },
  { name: "Tomás Ferreira", role: "Support", initials: "TF" },
]

export function AssignTask() {
  const [assignee, setAssignee] = useState("")
  const person = people.find((entry) => entry.name === assignee)

  return (
    <div className="flex flex-col gap-4">
      <div className="flex items-center gap-3 rounded-xl border border-border bg-card p-4">
        <div className="min-w-0 flex-1">
          <p className="truncate text-sm font-medium text-foreground">Update the pricing page</p>
          <p className="text-xs text-text-tertiary">Due Nov 14</p>
        </div>
        <div role="status" className="flex items-center gap-2 text-sm text-text-secondary">
          {person ? (
            <>
              <Avatar size="sm">
                <AvatarFallback>{person.initials}</AvatarFallback>
              </Avatar>
              {person.name}
            </>
          ) : (
            "Unassigned"
          )}
        </div>
      </div>
      <div className="flex flex-col gap-2">
        <Label htmlFor="assignee">Assignee</Label>
        <Autocomplete
          items={people}
          itemToStringValue={(person) => person.name}
          value={assignee}
          onValueChange={setAssignee}
        >
          <AutocompleteInputGroup>
            <AutocompleteInput id="assignee" placeholder="Search people" />
          </AutocompleteInputGroup>
          <AutocompletePopup>
            <AutocompleteEmpty>No one with that name.</AutocompleteEmpty>
            <AutocompleteList>
              {(person) => (
                <AutocompleteItem key={person.name} value={person} className="gap-3">
                  <Avatar size="sm">
                    <AvatarFallback>{person.initials}</AvatarFallback>
                  </Avatar>
                  <span className="flex flex-col">
                    <span className="text-foreground">{person.name}</span>
                    <span className="text-xs text-text-tertiary">{person.role}</span>
                  </span>
                </AutocompleteItem>
              )}
            </AutocompleteList>
          </AutocompletePopup>
        </Autocomplete>
      </div>
    </div>
  )
}
```

### Add a label, existing or new

The list offers the labels that exist. Add, or Enter, puts whatever is in the field on the issue, so a new label needs no second step.

```tsx
import { useState } from "react"
import {
  Autocomplete,
  AutocompleteInput,
  AutocompleteInputGroup,
  AutocompleteItem,
  AutocompleteList,
  AutocompletePopup,
} from "@/components/ui/autocomplete"
import { Badge } from "@/components/ui/badge"
import { Button } from "@/components/ui/button"
import { Label } from "@/components/ui/label"
import { Tag } from "lucide-react"

const suggestions = ["Design", "Engineering", "Marketing", "Research", "Support"]

export function AddLabel() {
  const [text, setText] = useState("")
  const [labels, setLabels] = useState<string[]>(["Research"])

  const add = (event: FormEvent) => {
    event.preventDefault()
    const label = text.trim()
    if (label && !labels.includes(label)) setLabels([...labels, label])
    setText("")
  }

  return (
    <form onSubmit={add} className="flex flex-col gap-4">
      <div className="flex min-h-6 flex-wrap items-center gap-2" role="status" aria-label="Labels on this issue">
        {labels.map((label) => (
          <Badge key={label}>{label}</Badge>
        ))}
      </div>
      <div className="flex flex-col gap-2">
        <Label htmlFor="label">Add a label</Label>
        <div className="flex gap-2">
          <Autocomplete items={suggestions} value={text} onValueChange={setText}>
            <AutocompleteInputGroup className="min-w-0 flex-1">
              <Tag className="size-4 text-text-tertiary" />
              <AutocompleteInput id="label" placeholder="Type a label" />
            </AutocompleteInputGroup>
            <AutocompletePopup>
              <AutocompleteList>
                {(item) => (
                  <AutocompleteItem key={item} value={item}>
                    {item}
                  </AutocompleteItem>
                )}
              </AutocompleteList>
            </AutocompletePopup>
          </Autocomplete>
          <Button type="submit" variant="plain">
            Add
          </Button>
        </div>
      </div>
    </form>
  )
}
```

## For AI agents

`get_component("autocomplete")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
