Combobox
A combobox is a text field with a list: people type to narrow the list, then pick one value with the mouse or the keyboard.
When to use
Section titled “When to use”- Use it for more than 15 options, or whenever people know what they look for, such as an artist, a song or a company.
- Use a Select for 4 to 15 options, and a Radio Group for 2 or 3.
- Write the empty text for the list, such as “Artis tidak ditemukan.”, so people know the search worked.
Searching on the server. When the list lives in the backend, search as people type: wait about 300ms after the last key, keep the previous results while the next ones load, and show a Spinner in the list. The backend decides what matches.
Anatomy
Section titled “Anatomy”- 1Input to type in
- 2Typed text and caret
- 3Matching option
- 4List
- Input: a text field on
radius-mdwith aninputborder,h-9tall. - List: a popup on
popoverwith aborder,radius-lgandshadow-lg, as wide as the input. - Item:
radius-md; the highlighted item isaccentand the chosen one has a check icon. - Empty text: shown when nothing matches.
Variants
Section titled “Variants”There is one style. React also has chips (ComboboxChips) for picking several values.
| React | Vue | Flutter | Type | Default | Use |
|---|---|---|---|---|---|
items on Combobox |
ComboboxItem children |
options on ShadSelect.withSearch |
list | none | The options. |
value / defaultValue |
v-model |
initialValue |
value | none | The chosen value. |
onValueChange |
@update:model-value |
onChanged |
function | none | Runs when a value is picked. |
placeholder on ComboboxInput |
placeholder on ComboboxInput |
placeholder |
text | none | Shown before a choice. |
ComboboxEmpty |
ComboboxEmpty |
an empty row in options |
text | none | Says nothing matched. |
onInputValueChange |
@update:model-value on ComboboxInput |
onSearchChanged |
function | none | Runs as people type, for server search. |
import { useId } from "react"import { Combobox, ComboboxContent, ComboboxEmpty, ComboboxInput, ComboboxItem, ComboboxList,} from "@/components/ui/combobox"import { Field, FieldLabel } from "@/components/ui/field"
const artists = ["Rara Senandika", "Bima Laras", "Nada Kirana", "Arka Wening", "Sinta Maharani", "Raka Pratama"]
export default function ComboboxDemo() { const id = useId() return ( <Field className="w-full max-w-xs"> <FieldLabel htmlFor={`${id}-artist`}>Artis</FieldLabel> <Combobox items={artists}> <ComboboxInput id={`${id}-artist`} placeholder="Pilih artis" /> <ComboboxContent> <ComboboxEmpty>Artis tidak ditemukan.</ComboboxEmpty> <ComboboxList> {(artist: string) => ( <ComboboxItem key={artist} value={artist}> {artist} </ComboboxItem> )} </ComboboxList> </ComboboxContent> </Combobox> </Field> )}<script setup lang="ts">import { ref, useId } from "vue"import { CheckIcon } from "@lucide/vue"import { Combobox, ComboboxAnchor, ComboboxEmpty, ComboboxInput, ComboboxItem, ComboboxItemIndicator, ComboboxList,} from "@/components/ui/combobox"import { Field, FieldLabel } from "@/components/ui/field"
const artists = ["Rara Senandika", "Bima Laras", "Nada Kirana", "Arka Wening", "Sinta Maharani", "Raka Pratama"]const id = useId()const artist = ref<string>()</script>
<template> <Field class="w-full max-w-xs"> <FieldLabel :for="`${id}-artist`">Artis</FieldLabel> <Combobox v-model="artist"> <ComboboxAnchor> <ComboboxInput :id="`${id}-artist`" placeholder="Pilih artis" :display-value="(value: string) => value ?? ''" /> </ComboboxAnchor> <ComboboxList> <ComboboxEmpty>Artis tidak ditemukan.</ComboboxEmpty> <ComboboxItem v-for="name in artists" :key="name" :value="name"> {{ name }} <ComboboxItemIndicator> <CheckIcon /> </ComboboxItemIndicator> </ComboboxItem> </ComboboxList> </Combobox> </Field></template>import 'package:flutter/widgets.dart';import 'package:shadcn_ui/shadcn_ui.dart';
const artists = ['Rara Senandika', 'Bima Laras', 'Nada Kirana', 'Arka Wening', 'Sinta Maharani', 'Raka Pratama'];
class ComboboxDemo extends StatefulWidget { const ComboboxDemo({super.key});
@override State<ComboboxDemo> createState() => _ComboboxDemoState();}
class _ComboboxDemoState extends State<ComboboxDemo> { String search = '';
@override Widget build(BuildContext context) { final matches = artists.where((a) => a.toLowerCase().contains(search.toLowerCase())).toList(); return Column( mainAxisSize: MainAxisSize.min, crossAxisAlignment: CrossAxisAlignment.start, spacing: 8, children: [ Text('Artis', style: ShadTheme.of(context).textTheme.small), ShadSelect<String>.withSearch( minWidth: 280, placeholder: const Text('Pilih artis'), searchPlaceholder: const Text('Cari artis'), onSearchChanged: (value) => setState(() => search = value), options: [ if (matches.isEmpty) const Padding(padding: EdgeInsets.symmetric(vertical: 24), child: Text('Artis tidak ditemukan.')), for (final artist in matches) ShadOption(value: artist, child: Text(artist)), ], selectedOptionBuilder: (context, value) => Text(value), ), ], ); }}Install
Section titled “Install”npx shadcn@latest add https://design.sosialoka.tech/r/react/combobox.jsonnpx shadcn-vue@latest add https://design.sosialoka.tech/r/vue/combobox.jsonAccessibility
Section titled “Accessibility”- The input has
role="combobox"and a visible label; the list hasrole="listbox"and its itemsrole="option". - Typing filters the list. Arrow keys move through the items, Enter picks one, and Escape closes the list without changing the value.
- The empty text is read when nothing matches.
