Skip to content
Shaken UI
Sign in

Combobox

Save

A 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

Installation

npx @shakenui/cli add combobox

Review the plan first. A dry run lists every file and package without changing anything:

npx @shakenui/cli add combobox --dry-run

Usage

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

PropTypeDefaultDescription
itemsItem[]—Combobox: the items to filter. { value, label } objects need no extra props.
value / defaultValueItem | Item[] | null—Combobox: the selection.
multiplebooleanfalseCombobox: collect several values; use ComboboxChipsInput.
filter(item, query) => boolean—Combobox: custom matching.
showClear / showTriggerbooleantrueComboboxInput: a clear button once a value is chosen, and a chevron that opens the list.
renderChip(item) => ReactNode—ComboboxChipsInput: a chip's content.
chipsLabelstring"Selected"ComboboxChipsInput: names the chip list for screen readers.
icon / metaReactNode—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.tsxShow
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}
    />
  );
}