# Combobox: Controlled

> Control the selection with `value` and `onValueChange`, and the popup with `open` and `onOpenChange`. Clearing sets the value to `null`.

Example: https://hextaui.com/docs/combobox/examples/controlled
Component docs: https://hextaui.com/docs/combobox.md

## Add this example

```bash
npx shadcn@latest add https://hextaui.com/r/combobox-controlled.json
```

This adds `components/examples/combobox/controlled.tsx` with the Combobox component and the HextaUI theme tokens.

## Source

```tsx title="components/examples/combobox/controlled.tsx"
"use client"

import * as React from "react"

import { Button } from "@/components/ui/button"
import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
} from "@/components/ui/combobox"
import { Label } from "@/components/ui/label"

const fruits = [
  "Apple",
  "Apricot",
  "Banana",
  "Blackberry",
  "Blueberry",
  "Cherry",
  "Grape",
  "Grapefruit",
  "Kiwi",
  "Lychee",
  "Mango",
  "Orange",
  "Papaya",
  "Peach",
  "Pear",
  "Pineapple",
  "Plum",
  "Raspberry",
  "Strawberry",
  "Watermelon",
]

export function ComboboxControlled() {
  const [value, setValue] = React.useState<string | null>("Peach")
  const [open, setOpen] = React.useState(false)

  return (
    <div className="flex w-full max-w-xs flex-col gap-2">
      <Label htmlFor="combobox-controlled">Fruit</Label>
      <Combobox
        items={fruits}
        value={value}
        onValueChange={setValue}
        open={open}
        onOpenChange={setOpen}
      >
        <ComboboxInput
          id="combobox-controlled"
          placeholder="Select a fruit"
          showClear
        />
        <ComboboxContent>
          <ComboboxEmpty>No fruit found.</ComboboxEmpty>
          <ComboboxList>
            {(item: string) => (
              <ComboboxItem key={item} value={item}>
                {item}
              </ComboboxItem>
            )}
          </ComboboxList>
        </ComboboxContent>
      </Combobox>
      <div className="flex items-center gap-2">
        <Button size="sm" variant="outline" onClick={() => setValue("Kiwi")}>
          Pick Kiwi
        </Button>
        <Button size="sm" variant="outline" onClick={() => setOpen(!open)}>
          {open ? "Close" : "Open"}
        </Button>
      </div>
      <p className="text-sm text-muted-foreground">Value: {value ?? "none"}</p>
    </div>
  )
}
```

## Props in this example

### Combobox

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `Item[] \| Group[]` | – | The options. Filtered as you type and passed to the list’s render function. |
| `value` | `Value \| Value[] \| null` | – |  |
| `onValueChange` | `(value, details) => void` | – |  |
| `open` | `boolean` | – |  |
| `onOpenChange` | `(open: boolean, details) => void` | – |  |

### ComboboxInput

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `showClear` | `boolean` | `false` | Show a clear button in the chevron’s place while there is a value. |
| `placeholder` | `string` | – |  |

### ComboboxItem

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `Item` | – | The item this row represents. |

## More Combobox examples

- [Clear button](https://hextaui.com/docs/combobox/examples/clear.md)
- [With icons](https://hextaui.com/docs/combobox/examples/icons.md)
- [Groups and separators](https://hextaui.com/docs/combobox/examples/groups.md)
- [Multiple](https://hextaui.com/docs/combobox/examples/multiple.md)
- [Search inside the popup](https://hextaui.com/docs/combobox/examples/popup-search.md)
- [Trigger rendered as a Button](https://hextaui.com/docs/combobox/examples/button-trigger.md)
- [Disabled, invalid and disabled items](https://hextaui.com/docs/combobox/examples/states.md)
- [Long content and large lists](https://hextaui.com/docs/combobox/examples/long-content.md)
- [Async search](https://hextaui.com/docs/combobox/examples/async.md)
- [Inside a sheet](https://hextaui.com/docs/combobox/examples/sheet.md)
- [Right to left](https://hextaui.com/docs/combobox/examples/rtl.md)