Combobox
SaveA searchable select that filters as you type, with an empty state, item icons and counts, and removable chips for multiple values.
- Category
- Forms
- Version
- 0.1.0
- Frameworks
- Next.js, Vite + React
- Styling
- Tailwind CSS v4
Preview
Combobox preview
Amara Okafor
Priya Raman
Installation
npx @shakenui/cli add comboboxReview the plan first. A dry run lists every file and package without changing anything:
npx @shakenui/cli add combobox --dry-runUsage
combobox-example.tsx
"use client";
import { useId } from "react";
import {
Combobox,
ComboboxChipsInput,
ComboboxContent,
ComboboxEmpty,
ComboboxInput,
ComboboxItem,
ComboboxList,
} from "@/components/shaken/ui/combobox";
interface Repository {
value: string;
label: string;
stars: string;
}
const repositories: Repository[] = [
{ value: "web", label: "northwind/web", stars: "2.4k" },
{ value: "api", label: "northwind/api", stars: "1.1k" },
{ value: "agents", label: "northwind/agents", stars: "860" },
{ value: "design-system", label: "northwind/design-system", stars: "540" },
{ value: "infra", label: "northwind/infra", stars: "210" },
{ value: "docs", label: "northwind/docs", stars: "96" },
];
const reviewers = [
{ value: "amara", label: "Amara Okafor" },
{ value: "kenji", label: "Kenji Watanabe" },
{ value: "lucia", label: "Lucía Fernández" },
{ value: "noah", label: "Noah Lindqvist" },
{ value: "priya", label: "Priya Raman" },
{ value: "tomas", label: "Tomás Novák" },
];
function RepoIcon() {
return (
<svg viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinejoin="round">
<path d="M3.5 12.5V3.25c0-.83.67-1.5 1.5-1.5h7.5v9.5H5a1.5 1.5 0 0 0-1.5 1.5zm0 0c0 .83.67 1.5 1.5 1.5h7.5" />
</svg>
);
}
export default function ComboboxExample() {
const repoId = useId();
const reviewersId = useId();
return (
<div className="grid w-full max-w-sm gap-6">
<Combobox items={repositories} defaultValue={repositories[2]}>
<div className="grid gap-1.5">
<label htmlFor={repoId} className="text-sm leading-5 font-medium text-zinc-950 dark:text-white">
Repository
</label>
<ComboboxInput id={repoId} placeholder="Search repositories" />
</div>
<ComboboxContent>
<ComboboxEmpty>No repositories match.</ComboboxEmpty>
<ComboboxList>
{(repo: Repository) => (
<ComboboxItem key={repo.value} value={repo} icon={<RepoIcon />} meta={repo.stars}>
{repo.label}
</ComboboxItem>
)}
</ComboboxList>
</ComboboxContent>
</Combobox>
<Combobox items={reviewers} multiple defaultValue={[reviewers[0], reviewers[4]]}>
<div className="grid gap-1.5">
<label htmlFor={reviewersId} className="text-sm leading-5 font-medium text-zinc-950 dark:text-white">
Reviewers
</label>
<ComboboxChipsInput id={reviewersId} chipsLabel="Selected reviewers" placeholder="Add people" />
</div>
<ComboboxContent>
<ComboboxEmpty>Nobody by that name.</ComboboxEmpty>
<ComboboxList>
{(person: (typeof reviewers)[number]) => (
<ComboboxItem key={person.value} value={person}>
{person.label}
</ComboboxItem>
)}
</ComboboxList>
</ComboboxContent>
</Combobox>
</div>
);
}API
| Prop | Type | Default | Description |
|---|---|---|---|
| items | Item[] | — | Combobox: the items to filter. { value, label } objects need no extra props. |
| value / defaultValue | Item | Item[] | null | — | Combobox: the selection. |
| multiple | boolean | false | Combobox: collect several values; use ComboboxChipsInput. |
| filter | (item, query) => boolean | — | Combobox: custom matching. |
| showClear / showTrigger | boolean | true | ComboboxInput: a clear button once a value is chosen, and a chevron that opens the list. |
| renderChip | (item) => ReactNode | — | ComboboxChipsInput: a chip's content. |
| chipsLabel | string | "Selected" | ComboboxChipsInput: names the chip list for screen readers. |
| icon / meta | ReactNode | — | ComboboxItem: a 16px icon and trailing secondary text. |
Accessibility
- The input has role="combobox" with aria-expanded and aria-activedescendant; options are role="option" in a listbox.
- Arrow keys move the highlight while focus stays in the input; Enter selects; Escape closes the list.
- In multiple mode, Backspace at the start of the input removes the last chip and Left Arrow moves focus onto the chips; every remove button is labeled "Remove <name>".
- The clear and open buttons are labeled "Clear selection" and "Show options".
- New chips scale in only with motion allowed.
Files
Installed into src/components/shaken, or components/shaken when the project has no src directory.
src/components/shaken/ui/combobox.tsxcombobox- npm packages: @base-ui/react@^1.9.0React and Tailwind CSS v4 required
Source
The exact source the CLI installs, from /r/items/react/combobox/0.1.0.json.
ui/combobox.tsxShowHide
ui/combobox.tsx
"use client";
import { Combobox as BaseCombobox } from "@base-ui/react/combobox";
import type { ComponentProps, ReactNode } from "react";
type ClassName<State> = string | ((state: State) => string | undefined) | undefined;
function cx(...classes: (string | false | null | undefined)[]) {
return classes.filter(Boolean).join(" ");
}
/** Prepends base classes while keeping Base UI's state-function form of className working. */
function withBase<State>(base: string, className: ClassName<State>) {
return typeof className === "function" ? (state: State) => cx(base, className(state)) : cx(base, className);
}
/** Reads a display string from a string item or a `{ label }` / `{ value }` object. */
function itemText(item: unknown): string {
if (item != null && typeof item === "object") {
const record = item as { label?: unknown; value?: unknown };
return String(record.label ?? record.value ?? "");
}
return String(item ?? "");
}
/**
* Groups the combobox parts. Pass `items` to filter them as the user types (objects shaped
* `{ value, label }` work without extra props), plus `defaultValue` or `value` + `onValueChange`.
* Add `multiple` to collect several values as chips.
*/
export const Combobox = BaseCombobox.Root;
/** Renders a nested list for grouped items: `{(item) => <ComboboxItem value={item} />}`. */
export const ComboboxCollection = BaseCombobox.Collection;
const fieldShell = cx(
"relative flex w-full min-w-0 items-center rounded-lg border bg-white text-sm text-zinc-900 shadow-sm",
"border-zinc-300 dark:border-zinc-700 dark:bg-zinc-950 dark:text-zinc-100",
"transition-[border-color,box-shadow] duration-150 ease-out motion-reduce:transition-none",
"focus-within:border-sky-500 focus-within:ring-3 focus-within:ring-sky-500/20",
"data-[invalid]:border-red-400 data-[invalid]:focus-within:border-red-500 data-[invalid]:focus-within:ring-red-500/20 dark:data-[invalid]:border-red-500/60",
"data-[disabled]:cursor-not-allowed data-[disabled]:opacity-60",
);
const bareInput =
"h-full min-w-0 flex-1 bg-transparent text-sm outline-none placeholder:text-zinc-400 disabled:cursor-not-allowed dark:placeholder:text-zinc-500";
const iconButton = cx(
"flex size-7 shrink-0 cursor-default items-center justify-center rounded-md text-zinc-400 outline-none",
"hover:bg-zinc-950/[0.04] hover:text-zinc-700 dark:text-zinc-500 dark:hover:bg-white/[0.06] dark:hover:text-zinc-200",
"transition-colors duration-150 ease-out motion-reduce:transition-none",
"focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-sky-500 [&_svg]:size-4",
);
function ChevronIcon() {
return (
<svg aria-hidden="true" viewBox="0 0 16 16" fill="none">
<path d="M5.5 6.25L8 3.75l2.5 2.5M5.5 9.75L8 12.25l2.5-2.5" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" />
</svg>
);
}
function ClearIcon() {
return (
<svg aria-hidden="true" viewBox="0 0 16 16" fill="none">
<path d="M5 5l6 6M11 5l-6 6" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" />
</svg>
);
}
export interface ComboboxInputProps extends BaseCombobox.Input.Props {
/** Shows a button that clears the value once something is selected. */
showClear?: boolean;
/** Shows a chevron button that opens the list without typing. */
showTrigger?: boolean;
/** Classes for the bordered field around the input. `className` styles the input itself. */
containerClassName?: string;
}
/**
* The search field for a single-value combobox, styled like Input. Typing filters the list;
* arrow keys move the highlight; Enter picks; Escape closes and then clears.
* Label it with a `<label htmlFor>` pointing at its `id`, a Field, or `aria-label`.
*/
export function ComboboxInput({ showClear = true, showTrigger = true, containerClassName, className, ...props }: ComboboxInputProps) {
return (
<BaseCombobox.InputGroup className={cx(fieldShell, "h-9 pr-1 pl-3", containerClassName)}>
<BaseCombobox.Input className={withBase(bareInput, className)} {...props} />
<div className="flex items-center">
{showClear ? (
<BaseCombobox.Clear aria-label="Clear selection" className={iconButton}>
<ClearIcon />
</BaseCombobox.Clear>
) : null}
{showTrigger ? (
<BaseCombobox.Trigger aria-label="Show options" className={iconButton}>
<ChevronIcon />
</BaseCombobox.Trigger>
) : null}
</div>
</BaseCombobox.InputGroup>
);
}
export interface ComboboxChipsInputProps extends BaseCombobox.Input.Props {
/** Renders a chip's text. Defaults to the item's `label`, its `value`, or the item itself. */
renderChip?: (item: any) => ReactNode;
/** Names the selected chips for screen readers, for example "Selected reviewers". */
chipsLabel?: string;
/** Classes for the bordered field around the chips and input. `className` styles the input itself. */
containerClassName?: string;
}
/**
* The field for a multi-value combobox (`multiple` on the root): selected items sit as chips
* before the input and the field grows onto new lines as they fill it. Backspace at the start
* of the input removes the last chip; Left Arrow moves focus onto the chips.
*/
export function ComboboxChipsInput({
renderChip,
chipsLabel = "Selected",
placeholder,
containerClassName,
className,
...props
}: ComboboxChipsInputProps) {
return (
<BaseCombobox.InputGroup className={cx(fieldShell, "min-h-9 cursor-text px-1 py-1", containerClassName)}>
<BaseCombobox.Value>
{(value: unknown[]) => (
<BaseCombobox.Chips aria-label={value.length > 0 ? chipsLabel : undefined} className="flex w-full flex-wrap items-center gap-1">
{value.map((item) => {
const text = itemText(item);
return (
<BaseCombobox.Chip
key={text}
aria-label={text}
className={cx(
"inline-flex h-6.5 max-w-full cursor-default items-center gap-0.5 rounded-md border pr-0.5 pl-2 text-[13px] leading-none outline-none",
"border-zinc-950/10 bg-zinc-950/[0.03] text-zinc-800 dark:border-white/15 dark:bg-white/[0.05] dark:text-zinc-200",
"focus-within:border-zinc-950/30 focus-within:bg-zinc-950/[0.07] dark:focus-within:border-white/35 dark:focus-within:bg-white/[0.1]",
"data-[highlighted]:border-zinc-950/30 dark:data-[highlighted]:border-white/35",
// A new chip settles in from 90%; under reduced motion it appears in place.
"transition-[opacity,scale,background-color,border-color] duration-150 ease-out motion-reduce:transition-none",
"starting:opacity-0 motion-safe:starting:scale-90",
)}
>
<span className="truncate">{renderChip ? renderChip(item) : text}</span>
<BaseCombobox.ChipRemove
aria-label={`Remove ${text}`}
className={cx(
"flex size-5 shrink-0 cursor-default items-center justify-center rounded-[5px] text-zinc-400 outline-none",
"hover:bg-zinc-950/[0.06] hover:text-zinc-800 dark:text-zinc-500 dark:hover:bg-white/[0.08] dark:hover:text-white",
"transition-colors duration-150 ease-out motion-reduce:transition-none [&_svg]:size-3.5",
)}
>
<ClearIcon />
</BaseCombobox.ChipRemove>
</BaseCombobox.Chip>
);
})}
<BaseCombobox.Input
placeholder={value.length > 0 ? undefined : placeholder}
className={withBase(cx(bareInput, "h-6.5 min-w-20 px-1.5"), className)}
{...props}
/>
</BaseCombobox.Chips>
)}
</BaseCombobox.Value>
</BaseCombobox.InputGroup>
);
}
type PositionerProps = BaseCombobox.Positioner.Props;
export interface ComboboxContentProps extends BaseCombobox.Popup.Props {
/** Side of the field to place the list on. Flips when there is not enough room. */
side?: PositionerProps["side"];
/** Alignment against the field on the chosen side. */
align?: PositionerProps["align"];
/** Gap between the field and the list, in pixels. */
sideOffset?: PositionerProps["sideOffset"];
/** Classes for the positioner wrapper, for example to change the z-index. */
positionerClassName?: string;
/** Element to portal into. Defaults to `document.body`. */
container?: BaseCombobox.Portal.Props["container"];
}
/** The floating list panel, as wide as the field. Put ComboboxEmpty and ComboboxList inside. */
export function ComboboxContent({
side = "bottom",
align = "start",
sideOffset = 6,
positionerClassName,
container,
className,
...props
}: ComboboxContentProps) {
return (
<BaseCombobox.Portal container={container}>
<BaseCombobox.Positioner side={side} align={align} sideOffset={sideOffset} className={cx("z-50 outline-none", positionerClassName)}>
<BaseCombobox.Popup
className={withBase(
cx(
"w-(--anchor-width) max-w-(--available-width) origin-(--transform-origin) overflow-hidden rounded-xl outline-none",
"border border-zinc-950/10 bg-white text-zinc-950 shadow-[0_12px_32px_-8px_rgb(0_0_0/0.18)]",
"dark:border-white/15 dark:bg-black dark:text-white dark:shadow-[0_16px_48px_-12px_rgb(0_0_0/1),inset_0_1px_0_rgb(255_255_255/0.08)]",
"transition-[opacity,scale] duration-160 ease-[cubic-bezier(0.23,1,0.32,1)] motion-reduce:transition-none",
"data-[starting-style]:opacity-0 motion-safe:data-[starting-style]:scale-96",
"data-[ending-style]:opacity-0 data-[ending-style]:duration-110 data-[ending-style]:ease-out motion-safe:data-[ending-style]:scale-98",
),
className,
)}
{...props}
/>
</BaseCombobox.Positioner>
</BaseCombobox.Portal>
);
}
/** The scrolling list of options. Pass a function child to render each filtered item. */
export function ComboboxList({ className, ...props }: BaseCombobox.List.Props) {
return (
<BaseCombobox.List
className={withBase(
"max-h-[min(var(--available-height),20rem)] scroll-py-1.5 overflow-y-auto overscroll-contain p-1.5 outline-none data-[empty]:p-0",
className,
)}
{...props}
/>
);
}
/** Shown in place of the list when nothing matches the query. Renders nothing otherwise. */
export function ComboboxEmpty({ className, ...props }: BaseCombobox.Empty.Props) {
return (
<BaseCombobox.Empty
className={withBase(
"px-3 py-6 text-center text-sm leading-5 text-zinc-500 empty:m-0 empty:p-0 dark:text-zinc-400",
className,
)}
{...props}
/>
);
}
/**
* Announces async states such as "Searching…" or a result count to screen readers, and shows
* them in the list's tertiary text. Renders nothing while it has no children.
*/
export function ComboboxStatus({ className, ...props }: BaseCombobox.Status.Props) {
return (
<BaseCombobox.Status
className={withBase(
"flex items-center gap-2 px-3.5 py-2.5 text-sm leading-5 text-zinc-500 empty:m-0 empty:p-0 dark:text-zinc-400",
className,
)}
{...props}
/>
);
}
export interface ComboboxItemProps extends BaseCombobox.Item.Props {
/** A 16px icon before the text. */
icon?: ReactNode;
/** Secondary text at the end of the row, such as a count or a shortcut. */
meta?: ReactNode;
}
/**
* An option. Selected options carry a check at the end. The highlight moves instantly with the
* pointer and arrow keys.
*/
export function ComboboxItem({ icon, meta, className, children, ...props }: ComboboxItemProps) {
return (
<BaseCombobox.Item
className={withBase(
cx(
"relative flex h-8 cursor-default items-center gap-2.5 rounded-md pr-8 pl-2 text-sm outline-none select-none",
"text-zinc-700 data-[highlighted]:bg-zinc-950/[0.05] data-[highlighted]:text-zinc-950",
"dark:text-zinc-300 dark:data-[highlighted]:bg-white/[0.08] dark:data-[highlighted]:text-white",
"data-[selected]:text-zinc-950 dark:data-[selected]:text-white",
"data-[disabled]:pointer-events-none data-[disabled]:opacity-45",
"[&_svg]:size-4 [&_svg]:shrink-0",
),
className,
)}
{...props}
>
{icon != null ? (
<span aria-hidden="true" className="flex text-zinc-500 in-data-[highlighted]:text-zinc-950 dark:text-zinc-500 dark:in-data-[highlighted]:text-white">
{icon}
</span>
) : null}
<span className="min-w-0 flex-1 truncate">{children}</span>
{meta != null ? <span className="shrink-0 font-mono text-xs text-zinc-400 tabular-nums dark:text-zinc-500">{meta}</span> : null}
<BaseCombobox.ItemIndicator className="absolute right-2 flex text-zinc-950 dark:text-white">
<svg aria-hidden="true" viewBox="0 0 16 16" fill="none">
<path d="M3.75 8.25l2.75 2.75 5.75-6" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" />
</svg>
</BaseCombobox.ItemIndicator>
</BaseCombobox.Item>
);
}
/** Groups related options. Put a ComboboxGroupLabel inside to name the group. */
export function ComboboxGroup({ className, ...props }: BaseCombobox.Group.Props) {
return <BaseCombobox.Group className={withBase("not-first:mt-1", className)} {...props} />;
}
/** Names a ComboboxGroup. Must be rendered inside the group it labels. */
export function ComboboxGroupLabel({ className, ...props }: BaseCombobox.GroupLabel.Props) {
return (
<BaseCombobox.GroupLabel
className={withBase("px-2 pt-2 pb-1 text-xs font-medium text-zinc-500 select-none dark:text-zinc-500", className)}
{...props}
/>
);
}
/** A divider between groups of options. */
export function ComboboxSeparator({ className, ...props }: ComponentProps<typeof BaseCombobox.Separator>) {
return (
<BaseCombobox.Separator
className={withBase("-mx-1.5 my-1.5 h-px bg-zinc-950/[0.07] dark:bg-white/[0.08]", className)}
{...props}
/>
);
}