Combobox

1"use client";2​3import * as React from "react";4import { Popover as PopoverPrimitive } from "radix-ui";5import { Command as CommandPrimitive } from "cmdk";6import { CaretDownIcon, CheckIcon, MagnifyingGlassIcon, XIcon } from "@phosphor-icons/react/ssr";7​8import { usePortalContainer } from "@/lib/surface";9import { cn } from "@/lib/utils";10​11// A searchable choice (extrapolated from the Inkbox console, Figma 427:2715: the select trigger "Any State" and the12// command menu). The trigger is the select's white 40px key with 8px corners and the Shadow/S ring, the value in 14px ink13// (the placeholder in the light purple) and the bold caret at the right. It opens the menu panel (white, 8px corners,14// the floating shadow) from the trigger: a 44px search row with a magnifying glass, then 36px rows of 14px ink with the15// highlighted row on the lilac and a purple check beside the chosen ones; groups are headed in 13px purple. For several16// values, ComboboxChips is the field itself: lilac chips with 6px corners and an x, and a text input that filters as you17// type (Backspace on an empty input removes the last chip). Moving through the rows is instant: it is done by keyboard.18​19type Item = { value: string; label: string; disabled?: boolean };20​21type ComboboxContextValue = {22  multiple: boolean;23  values: string[];24  toggle: (value: string) => void;25  remove: (value: string) => void;26  open: boolean;27  setOpen: (open: boolean) => void;28  search: string;29  setSearch: (search: string) => void;30  labelOf: (value: string) => string;31  register: (value: string, label: string) => void;32  items?: Item[];33  disabled?: boolean;34  listRef: React.RefObject<HTMLDivElement | null>;35  chipsRef: React.RefObject<HTMLDivElement | null>;36  chips: boolean;37  setChips: (chips: boolean) => void;38  contentId: string;39};40​41const ComboboxContext = React.createContext<ComboboxContextValue | null>(null);42​43function useCombobox() {44  const context = React.useContext(ComboboxContext);45  if (!context) throw new Error("Combobox parts must be used within <Combobox>");46  return context;47}48​49type ComboboxBaseProps = {50  /** The choices, for labels while the list is closed and for ComboboxList's render function. */51  items?: (Item | string)[];52  open?: boolean;53  defaultOpen?: boolean;54  onOpenChange?: (open: boolean) => void;55  disabled?: boolean;56  /** The submitted name: one hidden input per chosen value. */57  name?: string;58  children?: React.ReactNode;59};60​61type ComboboxSingleProps = ComboboxBaseProps & { multiple?: false; value?: string | null; defaultValue?: string | null; onValueChange?: (value: string | null) => void };62type ComboboxMultipleProps = ComboboxBaseProps & { multiple: true; value?: string[]; defaultValue?: string[]; onValueChange?: (value: string[]) => void };63​64const normalize = (items?: (Item | string)[]) => items?.map((i) => (typeof i === "string" ? { value: i, label: i } : i));65​66function Combobox(props: ComboboxSingleProps | ComboboxMultipleProps) {67  const { open: openProp, defaultOpen = false, onOpenChange, disabled, name, children } = props;68  const multiple = props.multiple === true;69  const items = React.useMemo(() => normalize(props.items), [props.items]);70  const initial = props.defaultValue == null ? [] : Array.isArray(props.defaultValue) ? props.defaultValue : [props.defaultValue];71  const [inner, setInner] = React.useState<string[]>(initial);72  const controlled = props.value !== undefined;73  const values = controlled ? (props.value == null ? [] : Array.isArray(props.value) ? props.value : [props.value]) : inner;74  const [openInner, setOpenInner] = React.useState(defaultOpen);75  const open = openProp ?? openInner;76  const [search, setSearch] = React.useState("");77  const [chips, setChips] = React.useState(false);78  const labels = React.useRef(new Map<string, string>());79  const listRef = React.useRef<HTMLDivElement>(null);80  const chipsRef = React.useRef<HTMLDivElement>(null);81  const contentId = React.useId();82​83  const setOpen = React.useCallback(84    (next: boolean) => {85      if (openProp === undefined) setOpenInner(next);86      onOpenChange?.(next);87      if (!next) setSearch("");88    },89    [openProp, onOpenChange],90  );91  const commit = (next: string[]) => {92    if (!controlled) setInner(next);93    if (multiple) (props as ComboboxMultipleProps).onValueChange?.(next);94    else (props as ComboboxSingleProps).onValueChange?.(next[0] ?? null);95  };96  const toggle = (value: string) => {97    if (multiple) {98      commit(values.includes(value) ? values.filter((v) => v !== value) : [...values, value]);99      setSearch("");100    } else {101      // Picking the chosen value again keeps it; ComboboxClear empties the field.102      commit([value]);103      setOpen(false);104    }105  };106  const remove = (value: string) => commit(values.filter((v) => v !== value));107  const labelOf = (value: string) => labels.current.get(value) ?? items?.find((i) => i.value === value)?.label ?? value;108  const register = React.useCallback((value: string, label: string) => labels.current.set(value, label), []);109​110  return (111    <ComboboxContext.Provider value={{ multiple, values, toggle, remove, open, setOpen, search, setSearch, labelOf, register, items, disabled, listRef, chipsRef, chips, setChips, contentId }}>112      <PopoverPrimitive.Root data-slot="combobox" open={open} onOpenChange={setOpen}>113        {children}114      </PopoverPrimitive.Root>115      {name && values.map((v) => <input key={v} type="hidden" name={name} value={v} />)}116    </ComboboxContext.Provider>117  );118}119​120const FIELD =121  "flex min-h-10 w-full min-w-0 items-center gap-2 rounded-control bg-surface pr-3 pl-3.5 font-sans text-body leading-tight text-fg shadow-s outline-none transition-[box-shadow] duration-150 ease-out aria-invalid:shadow-[0_0_0_1px_var(--ds-color-status-danger)] motion-reduce:transition-none";122​123/** The closed field: the chosen value (ComboboxValue) and the caret. Opens the list. */124function ComboboxTrigger({ className, children, ...props }: React.ComponentProps<"button">) {125  const { open, disabled, values, contentId } = useCombobox();126  return (127    <PopoverPrimitive.Trigger asChild>128      <button129        type="button"130        role="combobox"131        aria-expanded={open}132        aria-controls={contentId}133        data-slot="combobox-trigger"134        data-empty={!values.length}135        disabled={disabled}136        className={cn(FIELD, "h-10 cursor-pointer text-left focus-visible:shadow-[var(--ds-shadow-s),var(--ds-shadow-focus)] disabled:cursor-not-allowed disabled:bg-subtle disabled:text-fg-muted data-[empty=true]:text-fg-subtle", className)}137        {...props}138      >139        <span className="flex min-w-0 flex-1 items-center gap-2 truncate">{children ?? <ComboboxValue />}</span>140        <CaretDownIcon aria-hidden weight="bold" className="size-4 shrink-0 text-fg" />141      </button>142    </PopoverPrimitive.Trigger>143  );144}145​146/** The chosen value's label, the chosen labels joined, or the placeholder. */147function ComboboxValue({ placeholder = "Select", children }: { placeholder?: string; children?: (values: string[]) => React.ReactNode }) {148  const { values, labelOf } = useCombobox();149  if (children) return <>{children(values)}</>;150  return <span data-slot="combobox-value">{values.length ? values.map(labelOf).join(", ") : placeholder}</span>;151}152​153/** Clears every chosen value. Put it inside ComboboxChips or beside a trigger. */154function ComboboxClear({ className, ...props }: React.ComponentProps<"button">) {155  const { values, remove, disabled } = useCombobox();156  if (!values.length) return null;157  return (158    <button159      type="button"160      data-slot="combobox-clear"161      aria-label="Clear"162      disabled={disabled}163      onClick={(e) => {164        e.stopPropagation();165        values.forEach(remove);166      }}167      className={cn("inline-flex size-6 shrink-0 items-center justify-center rounded-sm text-fg-faint outline-none transition-colors duration-150 ease-out hover:text-fg-muted focus-visible:outline-2 focus-visible:outline-focus-ring motion-reduce:transition-none", className)}168      {...props}169    >170      <XIcon weight="bold" className="size-4" />171    </button>172  );173}174​175function ComboboxContent({ className, children, align = "start", sideOffset = 6, anchor, onInteractOutside, ...props }: React.ComponentProps<typeof PopoverPrimitive.Content> & { anchor?: React.RefObject<HTMLElement | null> }) {176  const container = usePortalContainer();177  const { search, chips, listRef, chipsRef, contentId, open } = useCombobox();178  // With chips cmdk does not filter, so it would keep a hidden row highlighted: highlight the first match instead.179  const [active, setActive] = React.useState("");180  React.useEffect(() => {181    if (!chips || !open) return;182    const frame = requestAnimationFrame(() => setActive(listRef.current?.querySelector("[cmdk-item]:not([data-disabled=true])")?.getAttribute("data-value") ?? ""));183    return () => cancelAnimationFrame(frame);184  }, [chips, open, search, listRef]);185  return (186    <>187    {anchor && <PopoverPrimitive.Anchor virtualRef={anchor as React.RefObject<HTMLElement>} />}188    <PopoverPrimitive.Portal container={container}>189      <PopoverPrimitive.Content190        id={contentId}191        data-slot="combobox-content"192        align={align}193        sideOffset={sideOffset}194        // With chips the typing stays in the field; the list follows it.195        onOpenAutoFocus={chips ? (e) => e.preventDefault() : undefined}196        onInteractOutside={(e) => {197          onInteractOutside?.(e);198          // A press in the chips field keeps the list open: the field is where the typing happens.199          if (chips && chipsRef.current?.contains(e.target as Node)) e.preventDefault();200        }}201        className={cn(202          "z-50 w-(--radix-popover-trigger-width) min-w-56 max-w-[calc(100vw-2rem)] origin-(--radix-popover-content-transform-origin) overflow-hidden rounded-control bg-surface text-fg shadow-floating outline-none data-[state=closed]:animate-pop-out data-[state=open]:animate-pop-in",203          className,204        )}205        {...props}206      >207        <CommandPrimitive ref={listRef} shouldFilter={!chips} {...(chips ? { value: active, onValueChange: setActive } : {})} className="flex flex-col">208          {children}209        </CommandPrimitive>210      </PopoverPrimitive.Content>211    </PopoverPrimitive.Portal>212    </>213  );214}215​216/** The search row at the top of the list. */217function ComboboxInput({ className, placeholder = "Search", ...props }: Omit<React.ComponentProps<typeof CommandPrimitive.Input>, "value" | "onValueChange">) {218  const { search, setSearch } = useCombobox();219  return (220    <div data-slot="combobox-input-wrapper" className="flex h-11 shrink-0 items-center gap-2.5 border-b border-line-subtle px-3.5">221      <MagnifyingGlassIcon aria-hidden className="size-5.5 shrink-0 text-fg-muted" />222      <CommandPrimitive.Input223        data-slot="combobox-input"224        value={search}225        onValueChange={setSearch}226        placeholder={placeholder}227        className={cn("h-full w-full min-w-0 bg-transparent font-sans text-body leading-tight text-fg outline-none placeholder:text-fg-subtle", className)}228        {...props}229      />230    </div>231  );232}233​234/** The rows. Pass items as children, or a function that renders each of the Combobox's items. */235function ComboboxList({ className, children, ...props }: Omit<React.ComponentProps<typeof CommandPrimitive.List>, "children"> & { children?: React.ReactNode | ((item: Item) => React.ReactNode) }) {236  const { items } = useCombobox();237  return (238    <CommandPrimitive.List data-slot="combobox-list" className={cn("max-h-72 scroll-py-1 overflow-x-hidden overflow-y-auto overscroll-contain p-1", className)} {...props}>239      {typeof children === "function" ? items?.map((item) => <React.Fragment key={item.value}>{children(item)}</React.Fragment>) : children}240    </CommandPrimitive.List>241  );242}243​244/** Renders a group's own items with a function, inside a ComboboxGroup. */245function ComboboxCollection({ items, children }: { items: (Item | string)[]; children: (item: Item) => React.ReactNode }) {246  return <>{normalize(items)?.map((item) => <React.Fragment key={item.value}>{children(item)}</React.Fragment>)}</>;247}248​249function ComboboxItem({ value, label, className, children, disabled, ...props }: Omit<React.ComponentProps<typeof CommandPrimitive.Item>, "value" | "onSelect"> & { value: string; label?: string }) {250  const { values, toggle, register, chips, search } = useCombobox();251  const text = label ?? (typeof children === "string" ? children : value);252  React.useEffect(() => {253    register(value, text);254  }, [register, value, text]);255  // With chips, cmdk does not filter (the typing is outside it): hide rows that do not match here.256  if (chips && search && !text.toLowerCase().includes(search.toLowerCase())) return null;257  const selected = values.includes(value);258  return (259    <CommandPrimitive.Item260      data-slot="combobox-item"261      value={`${text} ${value}`}262      disabled={disabled}263      data-checked={selected || undefined}264      onSelect={() => toggle(value)}265      className={cn(266        "relative flex h-9 cursor-default items-center gap-2.5 rounded-control pr-8 pl-2.5 font-sans text-body leading-tight text-fg outline-none select-none data-[disabled=true]:pointer-events-none data-[disabled=true]:opacity-50 data-[selected=true]:bg-subtle [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-5.5 [&_svg:not([class*='text-'])]:text-icon-secondary",267        className,268      )}269      {...props}270    >271      {children ?? text}272      {selected && <CheckIcon aria-hidden weight="bold" className="absolute right-2.5 size-4 text-fg-brand" />}273    </CommandPrimitive.Item>274  );275}276​277function ComboboxEmpty({ className, children = "No results.", ...props }: React.ComponentProps<typeof CommandPrimitive.Empty>) {278  const { chips, search, items, labelOf, values } = useCombobox();279  // cmdk's own empty state only knows its filter; with chips, decide here.280  if (chips) {281    const any = (items ?? values.map((v) => ({ value: v, label: labelOf(v) }))).some((i) => !search || i.label.toLowerCase().includes(search.toLowerCase()));282    if (any) return null;283    return (284      <div data-slot="combobox-empty" className={cn("py-6 text-center text-body text-fg-muted", className)}>285        {children}286      </div>287    );288  }289  return (290    <CommandPrimitive.Empty data-slot="combobox-empty" className={cn("py-6 text-center text-body text-fg-muted", className)} {...props}>291      {children}292    </CommandPrimitive.Empty>293  );294}295​296function ComboboxGroup({ className, ...props }: React.ComponentProps<typeof CommandPrimitive.Group>) {297  return (298    <CommandPrimitive.Group299      data-slot="combobox-group"300      className={cn("overflow-hidden text-fg [&_[cmdk-group-heading]]:px-2.5 [&_[cmdk-group-heading]]:pt-2 [&_[cmdk-group-heading]]:pb-1 [&_[cmdk-group-heading]]:text-body-sm [&_[cmdk-group-heading]]:leading-tight [&_[cmdk-group-heading]]:text-fg-label", className)}301      {...props}302    />303  );304}305​306/** A heading inside the list that is not a group's (a note above the rows). */307function ComboboxLabel({ className, ...props }: React.ComponentProps<"div">) {308  return <div data-slot="combobox-label" className={cn("px-2.5 pt-2 pb-1 text-body-sm leading-tight text-fg-label", className)} {...props} />;309}310​311function ComboboxSeparator({ className, ...props }: React.ComponentProps<typeof CommandPrimitive.Separator>) {312  return <CommandPrimitive.Separator data-slot="combobox-separator" className={cn("-mx-1 my-1 h-px bg-line-subtle", className)} {...props} />;313}314​315/** The field for several values: chips and a text input, anchoring the list. */316function ComboboxChips({ className, children, ...props }: React.ComponentProps<"div">) {317  const { setChips, setOpen, disabled, chipsRef } = useCombobox();318  React.useEffect(() => {319    setChips(true);320    return () => setChips(false);321  }, [setChips]);322  return (323    <PopoverPrimitive.Anchor asChild>324      <div325        ref={chipsRef}326        data-slot="combobox-chips"327        data-disabled={disabled || undefined}328        onMouseDown={(e) => {329          if (disabled || e.target !== e.currentTarget) return;330          e.preventDefault();331          e.currentTarget.querySelector("input")?.focus();332          setOpen(true);333        }}334        className={cn(FIELD, "flex-wrap gap-1.5 py-1.5 has-[input:focus-visible]:shadow-[var(--ds-shadow-s),var(--ds-shadow-focus)] data-disabled:bg-subtle data-disabled:text-fg-muted", className)}335        {...props}336      >337        {children}338      </div>339    </PopoverPrimitive.Anchor>340  );341}342​343function ComboboxChip({ value, className, children, ...props }: React.ComponentProps<"span"> & { value: string }) {344  const { remove, labelOf, disabled } = useCombobox();345  return (346    <span data-slot="combobox-chip" className={cn("inline-flex h-7 max-w-full items-center gap-1 rounded-sm bg-subtle pr-1 pl-2 text-body leading-tight text-fg", className)} {...props}>347      <span className="truncate">{children ?? labelOf(value)}</span>348      <button349        type="button"350        aria-label={`Remove ${labelOf(value)}`}351        disabled={disabled}352        onClick={() => remove(value)}353        className="inline-flex size-5 items-center justify-center rounded-xs text-fg-muted outline-none transition-colors duration-150 ease-out hover:bg-subtle-hover hover:text-fg focus-visible:outline-2 focus-visible:outline-focus-ring motion-reduce:transition-none"354      >355        <XIcon weight="bold" className="size-3.5" />356      </button>357    </span>358  );359}360​361/** The typing part of ComboboxChips: filters the list; arrows and Enter work the list; Backspace removes the last chip. */362function ComboboxChipsInput({ className, onKeyDown, ...props }: React.ComponentProps<"input">) {363  const { search, setSearch, setOpen, open, values, remove, listRef, disabled, contentId } = useCombobox();364  return (365    <input366      data-slot="combobox-chips-input"367      role="combobox"368      aria-expanded={open}369      aria-controls={contentId}370      aria-autocomplete="list"371      disabled={disabled}372      value={search}373      onChange={(e) => {374        setSearch(e.target.value);375        if (!open) setOpen(true);376      }}377      onFocus={() => setOpen(true)}378      onKeyDown={(e) => {379        onKeyDown?.(e);380        if (e.defaultPrevented) return;381        if (e.key === "Backspace" && !search && values.length) remove(values[values.length - 1]);382        else if (["ArrowDown", "ArrowUp", "Enter", "Home", "End"].includes(e.key) && open && listRef.current) {383          e.preventDefault();384          // Hand the key to the list, which moves the highlight or picks the highlighted row.385          listRef.current.dispatchEvent(new KeyboardEvent("keydown", { key: e.key, bubbles: true, cancelable: true }));386        } else if (e.key === "ArrowDown" && !open) setOpen(true);387      }}388      className={cn("h-7 min-w-24 flex-1 bg-transparent font-sans text-body leading-tight text-fg outline-none placeholder:text-fg-subtle disabled:cursor-not-allowed", className)}389      {...props}390    />391  );392}393​394/** A ref for an element the list should open from, when it is not the trigger (pass it to ComboboxContent's anchor). */395function useComboboxAnchor<T extends HTMLElement = HTMLDivElement>() {396  return React.useRef<T>(null);397}398​399export {400  Combobox,401  ComboboxChip,402  ComboboxChips,403  ComboboxChipsInput,404  ComboboxClear,405  ComboboxCollection,406  ComboboxContent,407  ComboboxEmpty,408  ComboboxGroup,409  ComboboxInput,410  ComboboxItem,411  ComboboxLabel,412  ComboboxList,413  ComboboxSeparator,414  ComboboxTrigger,415  ComboboxValue,416  useCombobox,417  useComboboxAnchor,418};