---
title: Combobox
description: Autocomplete input with a list of suggestions.
---

```templ
package examples

import "github.com/axadrn/shadcn-templ/v2/components/combobox"

templ ComboboxDemo() {
	@combobox.Combobox() {
		@combobox.Input(combobox.InputProps{Placeholder: "Select a framework"})
		@combobox.Content() {
			@combobox.Empty() {
				No items found.
			}
			@combobox.List() {
				@combobox.Item(combobox.ItemProps{Value: "templ"}) {
					templ
				}
				@combobox.Item(combobox.ItemProps{Value: "htmx"}) {
					htmx
				}
				@combobox.Item(combobox.ItemProps{Value: "gin"}) {
					Gin
				}
				@combobox.Item(combobox.ItemProps{Value: "echo"}) {
					Echo
				}
				@combobox.Item(combobox.ItemProps{Value: "chi"}) {
					Chi
				}
			}
		}
	}
}
```

## Installation

<CodeTabs>

<TabsList>
  <TabsTrigger value="cli">Command</TabsTrigger>
  <TabsTrigger value="manual">Manual</TabsTrigger>
</TabsList>
<TabsContent value="cli">

```bash
shadcn-templ add combobox
```

</TabsContent>

<TabsContent value="manual">

<Steps className="mb-0 pt-2">

<Step>Copy and paste the following code into your project.</Step>

<ComponentSource name="combobox" title="components/combobox/combobox.templ" />

<ComponentSource name="combobox" title="components/combobox/combobox.js" />

<ComponentSource name="combobox" title="components/floatingui/floating_ui_core.js" />

<ComponentSource name="combobox" title="components/floatingui/floating_ui_dom.js" />

Component scripts are loaded through the shared script bundle, see [JavaScript](/docs/installation#javascript).

<Step>Update the import paths to match your project setup.</Step>

</Steps>

</TabsContent>

</CodeTabs>

## Usage

```go showLineNumbers
import "github.com/axadrn/shadcn-templ/v2/components/combobox"
```

```templ showLineNumbers
@combobox.Combobox() {
	@combobox.Input(combobox.InputProps{Placeholder: "Select a framework"})
	@combobox.Content() {
		@combobox.Empty() {
			No items found.
		}
		@combobox.List() {
			@combobox.Item(combobox.ItemProps{Value: "templ"}) {
				templ
			}
			@combobox.Item(combobox.ItemProps{Value: "htmx"}) {
				htmx
			}
		}
	}
}
```

## Composition

### Simple

A single-line input and a flat list (see [Basic](#basic)).

```text
combobox.Combobox
├── combobox.Input
└── combobox.Content
    ├── combobox.Empty
    └── combobox.List
        ├── combobox.Item
        └── combobox.Item
```

### With chips

Multi-select with `Multiple`, chips, and a chips input (see [Multiple](#multiple)).

```text
combobox.Combobox
├── combobox.Chips
│   ├── combobox.Value
│   │   └── combobox.Chip
│   └── combobox.ChipsInput
└── combobox.Content
    ├── combobox.Empty
    └── combobox.List
        ├── combobox.Item
        └── combobox.Item
```

### With groups

Nested items per group, with a separator between groups (see [Groups](#groups)).

```text
combobox.Combobox
├── combobox.Input
└── combobox.Content
    ├── combobox.Empty
    └── combobox.List
        ├── combobox.Group
        │   ├── combobox.Label
        │   ├── combobox.Item
        │   └── combobox.Item
        ├── combobox.Separator
        └── combobox.Group
            ├── combobox.Label
            ├── combobox.Item
            └── combobox.Item
```

## Custom Items

Use the `Label` prop when the text shown in the input differs from the item's value.

```templ showLineNumbers
@combobox.Combobox() {
	@combobox.Input(combobox.InputProps{Placeholder: "Select a framework"})
	@combobox.Content() {
		@combobox.Empty() {
			No items found.
		}
		@combobox.List() {
			@combobox.Item(combobox.ItemProps{Value: "next", Label: "Next.js"}) {
				Next.js
			}
			@combobox.Item(combobox.ItemProps{Value: "sveltekit", Label: "SvelteKit"}) {
				SvelteKit
			}
		}
	}
}
```

## Multiple Selection

Use `Multiple` with chips for multi-select behavior.

```templ showLineNumbers
@combobox.Combobox(combobox.Props{Multiple: true}) {
	@combobox.Chips() {
		@combobox.Value()
		@combobox.ChipsInput(combobox.ChipsInputProps{Placeholder: "Add framework"})
	}
	@combobox.Content() {
		@combobox.Empty() {
			No items found.
		}
		@combobox.List() {
			@combobox.Item(combobox.ItemProps{Value: "templ"}) {
				templ
			}
			@combobox.Item(combobox.ItemProps{Value: "htmx"}) {
				htmx
			}
		}
	}
}
```

## Basic

A simple combobox with a list of frameworks.

```templ
package examples

import "github.com/axadrn/shadcn-templ/v2/components/combobox"

templ ComboboxBasic() {
	@combobox.Combobox() {
		@combobox.Input(combobox.InputProps{Placeholder: "Select a framework"})
		@combobox.Content() {
			@combobox.Empty() {
				No items found.
			}
			@combobox.List() {
				@combobox.Item(combobox.ItemProps{Value: "templ"}) {
					templ
				}
				@combobox.Item(combobox.ItemProps{Value: "htmx"}) {
					htmx
				}
				@combobox.Item(combobox.ItemProps{Value: "gin"}) {
					Gin
				}
				@combobox.Item(combobox.ItemProps{Value: "echo"}) {
					Echo
				}
				@combobox.Item(combobox.ItemProps{Value: "chi"}) {
					Chi
				}
			}
		}
	}
}
```

## Multiple

A combobox with multiple selection using `Multiple` and `combobox.Chips`.

```templ
package examples

import "github.com/axadrn/shadcn-templ/v2/components/combobox"

templ ComboboxMultiple() {
	@combobox.Combobox(combobox.Props{
		Multiple:      true,
		AutoHighlight: true,
		Values:        []string{"templ"},
	}) {
		@combobox.Chips(combobox.ChipsProps{Class: "w-full max-w-xs"}) {
			@combobox.Value()
			@combobox.ChipsInput()
		}
		@combobox.Content() {
			@combobox.Empty() {
				No items found.
			}
			@combobox.List() {
				@combobox.Item(combobox.ItemProps{Value: "templ"}) {
					templ
				}
				@combobox.Item(combobox.ItemProps{Value: "htmx"}) {
					htmx
				}
				@combobox.Item(combobox.ItemProps{Value: "gin"}) {
					Gin
				}
				@combobox.Item(combobox.ItemProps{Value: "echo"}) {
					Echo
				}
				@combobox.Item(combobox.ItemProps{Value: "chi"}) {
					Chi
				}
			}
		}
	}
}
```

## Clear Button

Use the `ShowClear` prop to show a clear button.

```templ
package examples

import "github.com/axadrn/shadcn-templ/v2/components/combobox"

templ ComboboxClear() {
	@combobox.Combobox(combobox.Props{Value: "templ"}) {
		@combobox.Input(combobox.InputProps{
			Placeholder: "Select a framework",
			ShowClear:   true,
		})
		@combobox.Content() {
			@combobox.Empty() {
				No items found.
			}
			@combobox.List() {
				@combobox.Item(combobox.ItemProps{Value: "templ"}) {
					templ
				}
				@combobox.Item(combobox.ItemProps{Value: "htmx"}) {
					htmx
				}
				@combobox.Item(combobox.ItemProps{Value: "gin"}) {
					Gin
				}
				@combobox.Item(combobox.ItemProps{Value: "echo"}) {
					Echo
				}
				@combobox.Item(combobox.ItemProps{Value: "chi"}) {
					Chi
				}
			}
		}
	}
}
```

## Groups

Use `combobox.Group` and `combobox.Separator` to group items.

```templ
package examples

import "github.com/axadrn/shadcn-templ/v2/components/combobox"

templ ComboboxGroups() {
	@combobox.Combobox() {
		@combobox.Input(combobox.InputProps{Placeholder: "Select a timezone"})
		@combobox.Content() {
			@combobox.Empty() {
				No timezones found.
			}
			@combobox.List() {
				@combobox.Group() {
					@combobox.Label() {
						Americas
					}
					@combobox.Item(combobox.ItemProps{Value: "new-york"}) {
						(GMT-5) New York
					}
					@combobox.Item(combobox.ItemProps{Value: "los-angeles"}) {
						(GMT-8) Los Angeles
					}
					@combobox.Item(combobox.ItemProps{Value: "chicago"}) {
						(GMT-6) Chicago
					}
					@combobox.Item(combobox.ItemProps{Value: "toronto"}) {
						(GMT-5) Toronto
					}
					@combobox.Item(combobox.ItemProps{Value: "vancouver"}) {
						(GMT-8) Vancouver
					}
					@combobox.Item(combobox.ItemProps{Value: "sao-paulo"}) {
						(GMT-3) São Paulo
					}
					@combobox.Separator()
				}
				@combobox.Group() {
					@combobox.Label() {
						Europe
					}
					@combobox.Item(combobox.ItemProps{Value: "london"}) {
						(GMT+0) London
					}
					@combobox.Item(combobox.ItemProps{Value: "paris"}) {
						(GMT+1) Paris
					}
					@combobox.Item(combobox.ItemProps{Value: "berlin"}) {
						(GMT+1) Berlin
					}
					@combobox.Item(combobox.ItemProps{Value: "rome"}) {
						(GMT+1) Rome
					}
					@combobox.Item(combobox.ItemProps{Value: "madrid"}) {
						(GMT+1) Madrid
					}
					@combobox.Item(combobox.ItemProps{Value: "amsterdam"}) {
						(GMT+1) Amsterdam
					}
					@combobox.Separator()
				}
				@combobox.Group() {
					@combobox.Label() {
						Asia/Pacific
					}
					@combobox.Item(combobox.ItemProps{Value: "tokyo"}) {
						(GMT+9) Tokyo
					}
					@combobox.Item(combobox.ItemProps{Value: "shanghai"}) {
						(GMT+8) Shanghai
					}
					@combobox.Item(combobox.ItemProps{Value: "singapore"}) {
						(GMT+8) Singapore
					}
					@combobox.Item(combobox.ItemProps{Value: "dubai"}) {
						(GMT+4) Dubai
					}
					@combobox.Item(combobox.ItemProps{Value: "sydney"}) {
						(GMT+11) Sydney
					}
					@combobox.Item(combobox.ItemProps{Value: "seoul"}) {
						(GMT+9) Seoul
					}
				}
			}
		}
	}
}
```

## Custom Items

You can render a custom component inside `combobox.Item`.

```templ
package examples

import (
	"github.com/axadrn/shadcn-templ/v2/components/combobox"
	"github.com/axadrn/shadcn-templ/v2/components/item"
)

type comboboxCountry struct {
	Code      string
	Value     string
	Label     string
	Continent string
}

var comboboxCountries = []comboboxCountry{
	{Code: "ar", Value: "argentina", Label: "Argentina", Continent: "South America"},
	{Code: "au", Value: "australia", Label: "Australia", Continent: "Oceania"},
	{Code: "br", Value: "brazil", Label: "Brazil", Continent: "South America"},
	{Code: "ca", Value: "canada", Label: "Canada", Continent: "North America"},
	{Code: "cn", Value: "china", Label: "China", Continent: "Asia"},
	{Code: "co", Value: "colombia", Label: "Colombia", Continent: "South America"},
	{Code: "eg", Value: "egypt", Label: "Egypt", Continent: "Africa"},
	{Code: "fr", Value: "france", Label: "France", Continent: "Europe"},
	{Code: "de", Value: "germany", Label: "Germany", Continent: "Europe"},
	{Code: "it", Value: "italy", Label: "Italy", Continent: "Europe"},
	{Code: "jp", Value: "japan", Label: "Japan", Continent: "Asia"},
	{Code: "ke", Value: "kenya", Label: "Kenya", Continent: "Africa"},
	{Code: "mx", Value: "mexico", Label: "Mexico", Continent: "North America"},
	{Code: "nz", Value: "new-zealand", Label: "New Zealand", Continent: "Oceania"},
	{Code: "ng", Value: "nigeria", Label: "Nigeria", Continent: "Africa"},
	{Code: "za", Value: "south-africa", Label: "South Africa", Continent: "Africa"},
	{Code: "kr", Value: "south-korea", Label: "South Korea", Continent: "Asia"},
	{Code: "gb", Value: "united-kingdom", Label: "United Kingdom", Continent: "Europe"},
	{Code: "us", Value: "united-states", Label: "United States", Continent: "North America"},
}

templ ComboboxCustom() {
	@combobox.Combobox() {
		@combobox.Input(combobox.InputProps{Placeholder: "Search countries..."})
		@combobox.Content() {
			@combobox.Empty() {
				No countries found.
			}
			@combobox.List() {
				for _, country := range comboboxCountries {
					@combobox.Item(combobox.ItemProps{Value: country.Value, Label: country.Label}) {
						@item.Item(item.Props{Size: item.SizeXs, Class: "p-0"}) {
							@item.Content() {
								@item.Title(item.TitleProps{Class: "whitespace-nowrap"}) {
									{ country.Label }
								}
								@item.Description() {
									{ country.Continent } ({ country.Code })
								}
							}
						}
					}
				}
			}
		}
	}
}
```

## Invalid

Use `aria-invalid` on `combobox.Input` to make the combobox invalid.

```templ
package examples

import "github.com/axadrn/shadcn-templ/v2/components/combobox"

templ ComboboxInvalid() {
	@combobox.Combobox() {
		@combobox.Input(combobox.InputProps{
			Placeholder: "Select a framework",
			Attributes:  templ.Attributes{"aria-invalid": "true"},
		})
		@combobox.Content() {
			@combobox.Empty() {
				No items found.
			}
			@combobox.List() {
				@combobox.Item(combobox.ItemProps{Value: "templ"}) {
					templ
				}
				@combobox.Item(combobox.ItemProps{Value: "htmx"}) {
					htmx
				}
				@combobox.Item(combobox.ItemProps{Value: "gin"}) {
					Gin
				}
				@combobox.Item(combobox.ItemProps{Value: "echo"}) {
					Echo
				}
				@combobox.Item(combobox.ItemProps{Value: "chi"}) {
					Chi
				}
			}
		}
	}
}
```

## Disabled

Use the `Disabled` prop to disable the combobox.

```templ
package examples

import "github.com/axadrn/shadcn-templ/v2/components/combobox"

templ ComboboxDisabled() {
	@combobox.Combobox(combobox.Props{Disabled: true}) {
		@combobox.Input(combobox.InputProps{Placeholder: "Select a framework"})
		@combobox.Content() {
			@combobox.Empty() {
				No items found.
			}
			@combobox.List() {
				@combobox.Item(combobox.ItemProps{Value: "templ"}) {
					templ
				}
				@combobox.Item(combobox.ItemProps{Value: "htmx"}) {
					htmx
				}
				@combobox.Item(combobox.ItemProps{Value: "gin"}) {
					Gin
				}
				@combobox.Item(combobox.ItemProps{Value: "echo"}) {
					Echo
				}
				@combobox.Item(combobox.ItemProps{Value: "chi"}) {
					Chi
				}
			}
		}
	}
}
```

## Auto Highlight

Use the `AutoHighlight` prop to automatically highlight the first item on filter.

```templ
package examples

import "github.com/axadrn/shadcn-templ/v2/components/combobox"

templ ComboboxAutoHighlight() {
	@combobox.Combobox(combobox.Props{AutoHighlight: true}) {
		@combobox.Input(combobox.InputProps{Placeholder: "Select a framework"})
		@combobox.Content() {
			@combobox.Empty() {
				No items found.
			}
			@combobox.List() {
				@combobox.Item(combobox.ItemProps{Value: "templ"}) {
					templ
				}
				@combobox.Item(combobox.ItemProps{Value: "htmx"}) {
					htmx
				}
				@combobox.Item(combobox.ItemProps{Value: "gin"}) {
					Gin
				}
				@combobox.Item(combobox.ItemProps{Value: "echo"}) {
					Echo
				}
				@combobox.Item(combobox.ItemProps{Value: "chi"}) {
					Chi
				}
			}
		}
	}
}
```

## Popup

You can trigger the combobox from a button or any other component by using the `combobox.Trigger` attributes. Move the `combobox.Input` inside the `combobox.Content`.

```templ
package examples

import (
	"github.com/axadrn/shadcn-templ/v2/components/button"
	"github.com/axadrn/shadcn-templ/v2/components/combobox"
	"github.com/axadrn/shadcn-templ/v2/components/icon"
)

templ ComboboxPopup() {
	@combobox.Combobox() {
		@button.Button(button.Props{
			Variant:    button.VariantOutline,
			Class:      "w-64 justify-between font-normal",
			Attributes: combobox.Trigger(ctx),
		}) {
			@combobox.Value(combobox.ValueProps{Placeholder: "Select country"})
			@icon.ChevronDown(icon.Props{Class: "pointer-events-none size-4 text-muted-foreground"})
		}
		@combobox.Content() {
			@combobox.Input(combobox.InputProps{
				Placeholder: "Search",
				HideTrigger: true,
			})
			@combobox.Empty() {
				No items found.
			}
			@combobox.List() {
				for _, country := range comboboxCountries {
					@combobox.Item(combobox.ItemProps{Value: country.Value, Label: country.Label}) {
						{ country.Label }
					}
				}
			}
		}
	}
}
```

## Input Group

You can add an addon to the combobox by using the `inputgroup.Addon` component inside the `combobox.Input`.

```templ
package examples

import (
	"github.com/axadrn/shadcn-templ/v2/components/combobox"
	"github.com/axadrn/shadcn-templ/v2/components/icon"
	"github.com/axadrn/shadcn-templ/v2/components/inputgroup"
)

templ ComboboxInputGroup() {
	@combobox.Combobox() {
		@combobox.Input(combobox.InputProps{Placeholder: "Select a timezone"}) {
			@inputgroup.Addon() {
				@icon.Globe()
			}
		}
		@combobox.Content(combobox.ContentProps{
			AlignOffset: -28,
			Class:       "w-60",
		}) {
			@combobox.Empty() {
				No timezones found.
			}
			@combobox.List() {
				@combobox.Group() {
					@combobox.Label() {
						Americas
					}
					@combobox.Item(combobox.ItemProps{Value: "new-york"}) {
						(GMT-5) New York
					}
					@combobox.Item(combobox.ItemProps{Value: "los-angeles"}) {
						(GMT-8) Los Angeles
					}
					@combobox.Item(combobox.ItemProps{Value: "chicago"}) {
						(GMT-6) Chicago
					}
				}
				@combobox.Group() {
					@combobox.Label() {
						Europe
					}
					@combobox.Item(combobox.ItemProps{Value: "london"}) {
						(GMT+0) London
					}
					@combobox.Item(combobox.ItemProps{Value: "paris"}) {
						(GMT+1) Paris
					}
					@combobox.Item(combobox.ItemProps{Value: "berlin"}) {
						(GMT+1) Berlin
					}
				}
				@combobox.Group() {
					@combobox.Label() {
						Asia/Pacific
					}
					@combobox.Item(combobox.ItemProps{Value: "tokyo"}) {
						(GMT+9) Tokyo
					}
					@combobox.Item(combobox.ItemProps{Value: "shanghai"}) {
						(GMT+8) Shanghai
					}
					@combobox.Item(combobox.ItemProps{Value: "singapore"}) {
						(GMT+8) Singapore
					}
				}
			}
		}
	}
}
```

## API Reference

### Combobox

The `Combobox` component is the root that manages filtering, selection and the form value.

| Prop            | Type       | Default |
| --------------- | ---------- | ------- |
| `Name`          | `string`   | -       |
| `Value`         | `string`   | -       |
| `Values`        | `[]string` | -       |
| `Multiple`      | `bool`     | `false` |
| `AutoHighlight` | `bool`     | `false` |
| `Disabled`      | `bool`     | `false` |

### Input

The `combobox.Input` component is the text input that filters the list.

| Prop          | Type     | Default |
| ------------- | -------- | ------- |
| `Placeholder` | `string` | -       |
| `HideTrigger` | `bool`   | `false` |
| `ShowClear`   | `bool`   | `false` |
| `Class`       | `string` | -       |

### Content

The `combobox.Content` component is the popup that holds the list.

| Prop          | Type                                             | Default      |
| ------------- | ------------------------------------------------ | ------------ |
| `Side`        | `SideTop \| SideRight \| SideBottom \| SideLeft` | `SideBottom` |
| `Align`       | `AlignStart \| AlignCenter \| AlignEnd`          | `AlignStart` |
| `SideOffset`  | `int`                                            | `6`          |
| `AlignOffset` | `int`                                            | `0`          |
| `Class`       | `string`                                         | -            |

### List

The `combobox.List` component holds the filterable items.

| Prop    | Type     | Default |
| ------- | -------- | ------- |
| `Class` | `string` | -       |

### Empty

The `combobox.Empty` component shows while no item matches the filter.

| Prop    | Type     | Default |
| ------- | -------- | ------- |
| `Class` | `string` | -       |

### Group

The `combobox.Group` component wraps related items.

| Prop    | Type     | Default |
| ------- | -------- | ------- |
| `Class` | `string` | -       |

### Label

The `combobox.Label` component titles a group.

| Prop    | Type     | Default |
| ------- | -------- | ------- |
| `Class` | `string` | -       |

### Item

The `combobox.Item` component is a selectable option.

| Prop       | Type     | Default |
| ---------- | -------- | ------- |
| `Value`    | `string` | -       |
| `Label`    | `string` | -       |
| `Disabled` | `bool`   | `false` |
| `Class`    | `string` | -       |

### Separator

The `combobox.Separator` component divides groups.

| Prop    | Type     | Default |
| ------- | -------- | ------- |
| `Class` | `string` | -       |

### Chips

The `combobox.Chips` component is the chip container and popup anchor in multiple mode, composed with `Value` and `ChipsInput`.

| Prop    | Type     | Default |
| ------- | -------- | ------- |
| `Class` | `string` | -       |

### Chip

The `combobox.Chip` component renders one selected value as a removable chip, rendered by `Value` in multiple mode.

| Prop         | Type     | Default |
| ------------ | -------- | ------- |
| `Value`      | `string` | -       |
| `HideRemove` | `bool`   | `false` |
| `Class`      | `string` | -       |

### ChipsInput

The `combobox.ChipsInput` component is the inline filter input rendered after the chips.

| Prop          | Type     | Default |
| ------------- | -------- | ------- |
| `Placeholder` | `string` | -       |
| `Class`       | `string` | -       |

### Value

The `combobox.Value` component renders the current selection: the selected chips in multiple mode, or the selected item's label inside a button trigger (see [Popup](#popup)).

| Prop          | Type     | Default |
| ------------- | -------- | ------- |
| `Placeholder` | `string` | -       |
| `Class`       | `string` | -       |