{
  "schemaVersion": 1,
  "target": "react",
  "name": "combobox",
  "version": "0.1.0",
  "category": "forms",
  "title": "Combobox",
  "description": "A searchable select that filters as you type, with an empty state, item icons and counts, and removable chips for multiple values.",
  "tags": [
    "form",
    "combobox",
    "autocomplete",
    "multi-select",
    "chips",
    "base-ui"
  ],
  "requires": {
    "projectTypes": [
      "next",
      "vite-react"
    ],
    "styling": "tailwind-v4"
  },
  "npmDependencies": {
    "@base-ui/react": "^1.9.0"
  },
  "registryDependencies": [],
  "docsPath": "/components/combobox",
  "props": [
    {
      "name": "items",
      "type": "Item[]",
      "description": "Combobox: the items to filter. { value, label } objects need no extra props."
    },
    {
      "name": "value / defaultValue",
      "type": "Item | Item[] | null",
      "description": "Combobox: the selection."
    },
    {
      "name": "multiple",
      "type": "boolean",
      "default": "false",
      "description": "Combobox: collect several values; use ComboboxChipsInput."
    },
    {
      "name": "filter",
      "type": "(item, query) => boolean",
      "description": "Combobox: custom matching."
    },
    {
      "name": "showClear / showTrigger",
      "type": "boolean",
      "default": "true",
      "description": "ComboboxInput: a clear button once a value is chosen, and a chevron that opens the list."
    },
    {
      "name": "renderChip",
      "type": "(item) => ReactNode",
      "description": "ComboboxChipsInput: a chip's content."
    },
    {
      "name": "chipsLabel",
      "type": "string",
      "default": "\"Selected\"",
      "description": "ComboboxChipsInput: names the chip list for screen readers."
    },
    {
      "name": "icon / meta",
      "type": "ReactNode",
      "description": "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."
  ],
  "states": [
    "closed",
    "open",
    "filtering",
    "empty",
    "selected",
    "chips",
    "disabled"
  ],
  "files": [
    {
      "path": "ui/combobox.tsx",
      "content": "\"use client\";\n\nimport { Combobox as BaseCombobox } from \"@base-ui/react/combobox\";\nimport type { ComponentProps, ReactNode } from \"react\";\n\ntype ClassName<State> = string | ((state: State) => string | undefined) | undefined;\n\nfunction cx(...classes: (string | false | null | undefined)[]) {\n  return classes.filter(Boolean).join(\" \");\n}\n\n/** Prepends base classes while keeping Base UI's state-function form of className working. */\nfunction withBase<State>(base: string, className: ClassName<State>) {\n  return typeof className === \"function\" ? (state: State) => cx(base, className(state)) : cx(base, className);\n}\n\n/** Reads a display string from a string item or a `{ label }` / `{ value }` object. */\nfunction itemText(item: unknown): string {\n  if (item != null && typeof item === \"object\") {\n    const record = item as { label?: unknown; value?: unknown };\n    return String(record.label ?? record.value ?? \"\");\n  }\n  return String(item ?? \"\");\n}\n\n/**\n * Groups the combobox parts. Pass `items` to filter them as the user types (objects shaped\n * `{ value, label }` work without extra props), plus `defaultValue` or `value` + `onValueChange`.\n * Add `multiple` to collect several values as chips.\n */\nexport const Combobox = BaseCombobox.Root;\n\n/** Renders a nested list for grouped items: `{(item) => <ComboboxItem value={item} />}`. */\nexport const ComboboxCollection = BaseCombobox.Collection;\n\nconst fieldShell = cx(\n  \"relative flex w-full min-w-0 items-center rounded-lg border bg-white text-sm text-zinc-900 shadow-sm\",\n  \"border-zinc-300 dark:border-zinc-700 dark:bg-zinc-950 dark:text-zinc-100\",\n  \"transition-[border-color,box-shadow] duration-150 ease-out motion-reduce:transition-none\",\n  \"focus-within:border-sky-500 focus-within:ring-3 focus-within:ring-sky-500/20\",\n  \"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\",\n  \"data-[disabled]:cursor-not-allowed data-[disabled]:opacity-60\",\n);\n\nconst bareInput =\n  \"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\";\n\nconst iconButton = cx(\n  \"flex size-7 shrink-0 cursor-default items-center justify-center rounded-md text-zinc-400 outline-none\",\n  \"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\",\n  \"transition-colors duration-150 ease-out motion-reduce:transition-none\",\n  \"focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-sky-500 [&_svg]:size-4\",\n);\n\nfunction ChevronIcon() {\n  return (\n    <svg aria-hidden=\"true\" viewBox=\"0 0 16 16\" fill=\"none\">\n      <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\" />\n    </svg>\n  );\n}\n\nfunction ClearIcon() {\n  return (\n    <svg aria-hidden=\"true\" viewBox=\"0 0 16 16\" fill=\"none\">\n      <path d=\"M5 5l6 6M11 5l-6 6\" stroke=\"currentColor\" strokeWidth=\"1.5\" strokeLinecap=\"round\" />\n    </svg>\n  );\n}\n\nexport interface ComboboxInputProps extends BaseCombobox.Input.Props {\n  /** Shows a button that clears the value once something is selected. */\n  showClear?: boolean;\n  /** Shows a chevron button that opens the list without typing. */\n  showTrigger?: boolean;\n  /** Classes for the bordered field around the input. `className` styles the input itself. */\n  containerClassName?: string;\n}\n\n/**\n * The search field for a single-value combobox, styled like Input. Typing filters the list;\n * arrow keys move the highlight; Enter picks; Escape closes and then clears.\n * Label it with a `<label htmlFor>` pointing at its `id`, a Field, or `aria-label`.\n */\nexport function ComboboxInput({ showClear = true, showTrigger = true, containerClassName, className, ...props }: ComboboxInputProps) {\n  return (\n    <BaseCombobox.InputGroup className={cx(fieldShell, \"h-9 pr-1 pl-3\", containerClassName)}>\n      <BaseCombobox.Input className={withBase(bareInput, className)} {...props} />\n      <div className=\"flex items-center\">\n        {showClear ? (\n          <BaseCombobox.Clear aria-label=\"Clear selection\" className={iconButton}>\n            <ClearIcon />\n          </BaseCombobox.Clear>\n        ) : null}\n        {showTrigger ? (\n          <BaseCombobox.Trigger aria-label=\"Show options\" className={iconButton}>\n            <ChevronIcon />\n          </BaseCombobox.Trigger>\n        ) : null}\n      </div>\n    </BaseCombobox.InputGroup>\n  );\n}\n\nexport interface ComboboxChipsInputProps extends BaseCombobox.Input.Props {\n  /** Renders a chip's text. Defaults to the item's `label`, its `value`, or the item itself. */\n  renderChip?: (item: any) => ReactNode;\n  /** Names the selected chips for screen readers, for example \"Selected reviewers\". */\n  chipsLabel?: string;\n  /** Classes for the bordered field around the chips and input. `className` styles the input itself. */\n  containerClassName?: string;\n}\n\n/**\n * The field for a multi-value combobox (`multiple` on the root): selected items sit as chips\n * before the input and the field grows onto new lines as they fill it. Backspace at the start\n * of the input removes the last chip; Left Arrow moves focus onto the chips.\n */\nexport function ComboboxChipsInput({\n  renderChip,\n  chipsLabel = \"Selected\",\n  placeholder,\n  containerClassName,\n  className,\n  ...props\n}: ComboboxChipsInputProps) {\n  return (\n    <BaseCombobox.InputGroup className={cx(fieldShell, \"min-h-9 cursor-text px-1 py-1\", containerClassName)}>\n      <BaseCombobox.Value>\n        {(value: unknown[]) => (\n          <BaseCombobox.Chips aria-label={value.length > 0 ? chipsLabel : undefined} className=\"flex w-full flex-wrap items-center gap-1\">\n            {value.map((item) => {\n              const text = itemText(item);\n              return (\n                <BaseCombobox.Chip\n                  key={text}\n                  aria-label={text}\n                  className={cx(\n                    \"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\",\n                    \"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\",\n                    \"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]\",\n                    \"data-[highlighted]:border-zinc-950/30 dark:data-[highlighted]:border-white/35\",\n                    // A new chip settles in from 90%; under reduced motion it appears in place.\n                    \"transition-[opacity,scale,background-color,border-color] duration-150 ease-out motion-reduce:transition-none\",\n                    \"starting:opacity-0 motion-safe:starting:scale-90\",\n                  )}\n                >\n                  <span className=\"truncate\">{renderChip ? renderChip(item) : text}</span>\n                  <BaseCombobox.ChipRemove\n                    aria-label={`Remove ${text}`}\n                    className={cx(\n                      \"flex size-5 shrink-0 cursor-default items-center justify-center rounded-[5px] text-zinc-400 outline-none\",\n                      \"hover:bg-zinc-950/[0.06] hover:text-zinc-800 dark:text-zinc-500 dark:hover:bg-white/[0.08] dark:hover:text-white\",\n                      \"transition-colors duration-150 ease-out motion-reduce:transition-none [&_svg]:size-3.5\",\n                    )}\n                  >\n                    <ClearIcon />\n                  </BaseCombobox.ChipRemove>\n                </BaseCombobox.Chip>\n              );\n            })}\n            <BaseCombobox.Input\n              placeholder={value.length > 0 ? undefined : placeholder}\n              className={withBase(cx(bareInput, \"h-6.5 min-w-20 px-1.5\"), className)}\n              {...props}\n            />\n          </BaseCombobox.Chips>\n        )}\n      </BaseCombobox.Value>\n    </BaseCombobox.InputGroup>\n  );\n}\n\ntype PositionerProps = BaseCombobox.Positioner.Props;\n\nexport interface ComboboxContentProps extends BaseCombobox.Popup.Props {\n  /** Side of the field to place the list on. Flips when there is not enough room. */\n  side?: PositionerProps[\"side\"];\n  /** Alignment against the field on the chosen side. */\n  align?: PositionerProps[\"align\"];\n  /** Gap between the field and the list, in pixels. */\n  sideOffset?: PositionerProps[\"sideOffset\"];\n  /** Classes for the positioner wrapper, for example to change the z-index. */\n  positionerClassName?: string;\n  /** Element to portal into. Defaults to `document.body`. */\n  container?: BaseCombobox.Portal.Props[\"container\"];\n}\n\n/** The floating list panel, as wide as the field. Put ComboboxEmpty and ComboboxList inside. */\nexport function ComboboxContent({\n  side = \"bottom\",\n  align = \"start\",\n  sideOffset = 6,\n  positionerClassName,\n  container,\n  className,\n  ...props\n}: ComboboxContentProps) {\n  return (\n    <BaseCombobox.Portal container={container}>\n      <BaseCombobox.Positioner side={side} align={align} sideOffset={sideOffset} className={cx(\"z-50 outline-none\", positionerClassName)}>\n        <BaseCombobox.Popup\n          className={withBase(\n            cx(\n              \"w-(--anchor-width) max-w-(--available-width) origin-(--transform-origin) overflow-hidden rounded-xl outline-none\",\n              \"border border-zinc-950/10 bg-white text-zinc-950 shadow-[0_12px_32px_-8px_rgb(0_0_0/0.18)]\",\n              \"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)]\",\n              \"transition-[opacity,scale] duration-160 ease-[cubic-bezier(0.23,1,0.32,1)] motion-reduce:transition-none\",\n              \"data-[starting-style]:opacity-0 motion-safe:data-[starting-style]:scale-96\",\n              \"data-[ending-style]:opacity-0 data-[ending-style]:duration-110 data-[ending-style]:ease-out motion-safe:data-[ending-style]:scale-98\",\n            ),\n            className,\n          )}\n          {...props}\n        />\n      </BaseCombobox.Positioner>\n    </BaseCombobox.Portal>\n  );\n}\n\n/** The scrolling list of options. Pass a function child to render each filtered item. */\nexport function ComboboxList({ className, ...props }: BaseCombobox.List.Props) {\n  return (\n    <BaseCombobox.List\n      className={withBase(\n        \"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\",\n        className,\n      )}\n      {...props}\n    />\n  );\n}\n\n/** Shown in place of the list when nothing matches the query. Renders nothing otherwise. */\nexport function ComboboxEmpty({ className, ...props }: BaseCombobox.Empty.Props) {\n  return (\n    <BaseCombobox.Empty\n      className={withBase(\n        \"px-3 py-6 text-center text-sm leading-5 text-zinc-500 empty:m-0 empty:p-0 dark:text-zinc-400\",\n        className,\n      )}\n      {...props}\n    />\n  );\n}\n\n/**\n * Announces async states such as \"Searching…\" or a result count to screen readers, and shows\n * them in the list's tertiary text. Renders nothing while it has no children.\n */\nexport function ComboboxStatus({ className, ...props }: BaseCombobox.Status.Props) {\n  return (\n    <BaseCombobox.Status\n      className={withBase(\n        \"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\",\n        className,\n      )}\n      {...props}\n    />\n  );\n}\n\nexport interface ComboboxItemProps extends BaseCombobox.Item.Props {\n  /** A 16px icon before the text. */\n  icon?: ReactNode;\n  /** Secondary text at the end of the row, such as a count or a shortcut. */\n  meta?: ReactNode;\n}\n\n/**\n * An option. Selected options carry a check at the end. The highlight moves instantly with the\n * pointer and arrow keys.\n */\nexport function ComboboxItem({ icon, meta, className, children, ...props }: ComboboxItemProps) {\n  return (\n    <BaseCombobox.Item\n      className={withBase(\n        cx(\n          \"relative flex h-8 cursor-default items-center gap-2.5 rounded-md pr-8 pl-2 text-sm outline-none select-none\",\n          \"text-zinc-700 data-[highlighted]:bg-zinc-950/[0.05] data-[highlighted]:text-zinc-950\",\n          \"dark:text-zinc-300 dark:data-[highlighted]:bg-white/[0.08] dark:data-[highlighted]:text-white\",\n          \"data-[selected]:text-zinc-950 dark:data-[selected]:text-white\",\n          \"data-[disabled]:pointer-events-none data-[disabled]:opacity-45\",\n          \"[&_svg]:size-4 [&_svg]:shrink-0\",\n        ),\n        className,\n      )}\n      {...props}\n    >\n      {icon != null ? (\n        <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\">\n          {icon}\n        </span>\n      ) : null}\n      <span className=\"min-w-0 flex-1 truncate\">{children}</span>\n      {meta != null ? <span className=\"shrink-0 font-mono text-xs text-zinc-400 tabular-nums dark:text-zinc-500\">{meta}</span> : null}\n      <BaseCombobox.ItemIndicator className=\"absolute right-2 flex text-zinc-950 dark:text-white\">\n        <svg aria-hidden=\"true\" viewBox=\"0 0 16 16\" fill=\"none\">\n          <path d=\"M3.75 8.25l2.75 2.75 5.75-6\" stroke=\"currentColor\" strokeWidth=\"1.5\" strokeLinecap=\"round\" strokeLinejoin=\"round\" />\n        </svg>\n      </BaseCombobox.ItemIndicator>\n    </BaseCombobox.Item>\n  );\n}\n\n/** Groups related options. Put a ComboboxGroupLabel inside to name the group. */\nexport function ComboboxGroup({ className, ...props }: BaseCombobox.Group.Props) {\n  return <BaseCombobox.Group className={withBase(\"not-first:mt-1\", className)} {...props} />;\n}\n\n/** Names a ComboboxGroup. Must be rendered inside the group it labels. */\nexport function ComboboxGroupLabel({ className, ...props }: BaseCombobox.GroupLabel.Props) {\n  return (\n    <BaseCombobox.GroupLabel\n      className={withBase(\"px-2 pt-2 pb-1 text-xs font-medium text-zinc-500 select-none dark:text-zinc-500\", className)}\n      {...props}\n    />\n  );\n}\n\n/** A divider between groups of options. */\nexport function ComboboxSeparator({ className, ...props }: ComponentProps<typeof BaseCombobox.Separator>) {\n  return (\n    <BaseCombobox.Separator\n      className={withBase(\"-mx-1.5 my-1.5 h-px bg-zinc-950/[0.07] dark:bg-white/[0.08]\", className)}\n      {...props}\n    />\n  );\n}\n"
    }
  ],
  "example": {
    "content": "\"use client\";\n\nimport { useId } from \"react\";\nimport {\n  Combobox,\n  ComboboxChipsInput,\n  ComboboxContent,\n  ComboboxEmpty,\n  ComboboxInput,\n  ComboboxItem,\n  ComboboxList,\n} from \"@/components/shaken/ui/combobox\";\n\ninterface Repository {\n  value: string;\n  label: string;\n  stars: string;\n}\n\nconst repositories: Repository[] = [\n  { value: \"web\", label: \"northwind/web\", stars: \"2.4k\" },\n  { value: \"api\", label: \"northwind/api\", stars: \"1.1k\" },\n  { value: \"agents\", label: \"northwind/agents\", stars: \"860\" },\n  { value: \"design-system\", label: \"northwind/design-system\", stars: \"540\" },\n  { value: \"infra\", label: \"northwind/infra\", stars: \"210\" },\n  { value: \"docs\", label: \"northwind/docs\", stars: \"96\" },\n];\n\nconst reviewers = [\n  { value: \"amara\", label: \"Amara Okafor\" },\n  { value: \"kenji\", label: \"Kenji Watanabe\" },\n  { value: \"lucia\", label: \"Lucía Fernández\" },\n  { value: \"noah\", label: \"Noah Lindqvist\" },\n  { value: \"priya\", label: \"Priya Raman\" },\n  { value: \"tomas\", label: \"Tomás Novák\" },\n];\n\nfunction RepoIcon() {\n  return (\n    <svg viewBox=\"0 0 16 16\" fill=\"none\" stroke=\"currentColor\" strokeWidth=\"1.5\" strokeLinejoin=\"round\">\n      <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\" />\n    </svg>\n  );\n}\n\nexport default function ComboboxExample() {\n  const repoId = useId();\n  const reviewersId = useId();\n\n  return (\n    <div className=\"grid w-full max-w-sm gap-6\">\n      <Combobox items={repositories} defaultValue={repositories[2]}>\n        <div className=\"grid gap-1.5\">\n          <label htmlFor={repoId} className=\"text-sm leading-5 font-medium text-zinc-950 dark:text-white\">\n            Repository\n          </label>\n          <ComboboxInput id={repoId} placeholder=\"Search repositories\" />\n        </div>\n        <ComboboxContent>\n          <ComboboxEmpty>No repositories match.</ComboboxEmpty>\n          <ComboboxList>\n            {(repo: Repository) => (\n              <ComboboxItem key={repo.value} value={repo} icon={<RepoIcon />} meta={repo.stars}>\n                {repo.label}\n              </ComboboxItem>\n            )}\n          </ComboboxList>\n        </ComboboxContent>\n      </Combobox>\n\n      <Combobox items={reviewers} multiple defaultValue={[reviewers[0], reviewers[4]]}>\n        <div className=\"grid gap-1.5\">\n          <label htmlFor={reviewersId} className=\"text-sm leading-5 font-medium text-zinc-950 dark:text-white\">\n            Reviewers\n          </label>\n          <ComboboxChipsInput id={reviewersId} chipsLabel=\"Selected reviewers\" placeholder=\"Add people\" />\n        </div>\n        <ComboboxContent>\n          <ComboboxEmpty>Nobody by that name.</ComboboxEmpty>\n          <ComboboxList>\n            {(person: (typeof reviewers)[number]) => (\n              <ComboboxItem key={person.value} value={person}>\n                {person.label}\n              </ComboboxItem>\n            )}\n          </ComboboxList>\n        </ComboboxContent>\n      </Combobox>\n    </div>\n  );\n}\n"
  }
}
