components/combobox/combobox.react.tsx

Functions

Imports

It imports no other module of this repo. Imported by components/combobox/examples.tsx.

Source

1import { Combobox as Base } from "@base-ui/react/combobox";
2import { Fragment, useEffect, useId, useMemo, useRef, useState, type ReactNode, type RefObject } from "react";
3
4export interface ComboboxOption {
5  value: string;
6  label: string;
7  disabled?: boolean;
8  // A heading to list this option under. Options without one come first, ungrouped.
9  group?: string;
10}
11
12interface Group {
13  value: string;
14  items: ComboboxOption[];
15}
16
17export interface ComboboxBaseProps {
18  // The visible label above the box. Required: a combobox always has one.
19  label: string;
20  items: ComboboxOption[];
21  // An example only, never the label (patterns.md, "Form").
22  placeholder?: string;
23  // What an empty result says. A function gets the typed text, to name the filter.
24  emptyText?: ReactNode | ((query: string) => ReactNode);
25  // The items are still arriving: the popup says so instead of "no match".
26  loading?: boolean;
27  loadingText?: string;
28  // Help under the label, outside the box; also where a disabled box says why.
29  help?: ReactNode;
30  // The error, beside the field: marks the box invalid and describes it.
31  error?: ReactNode;
32  disabled?: boolean;
33  required?: boolean;
34  // The form field name of the hidden input that carries the value.
35  name?: string;
36  id?: string;
37  // Where the popup is portalled. Inside a modal <dialog> pass the dialog, or the popup
38  // renders under the top layer, out of sight.
39  container?: HTMLElement | null;
40  // For specimens and tests: open on mount, with this text typed.
41  defaultOpen?: boolean;
42  defaultInputValue?: string;
43}
44
45export interface ComboboxProps extends ComboboxBaseProps {
46  // The chosen value, controlled. Leave undefined to let the combobox hold it
47  // (defaultValue). null is "nothing chosen".
48  value?: string | null;
49  defaultValue?: string | null;
50  onValueChange?: (value: string | null) => void;
51  // A button in the box that clears the chosen value. It shows only while there is one.
52  clearable?: boolean;
53}
54
55export interface ComboboxMultipleProps extends ComboboxBaseProps {
56  // The chosen values, controlled. Leave undefined to let the combobox hold them.
57  values?: string[];
58  defaultValues?: string[];
59  onValuesChange?: (values: string[]) => void;
60  // A tag field: typed text that is not in `items` can be added as a value of its own. A first
61  // row, `Create “text”`, offers it; Enter takes it (text that matches an item, ignoring case, picks
62  // that item instead, so a tag is never made twice). The value of a made one is its text.
63  creatable?: boolean;
64  // The words of the create row, from the typed text.
65  createLabel?: (text: string) => string;
66}
67
68// A made value's id in the list, before it becomes a value: the prefix plus its text.
69const MAKE = "\u0001make:";
70const tidy = (text: string) => text.trim().replace(/\s+/g, " ");
71
72const Check = () => (
73  <svg width="16" height="16" viewBox="0 0 16 16" aria-hidden="true" focusable="false">
74    <path fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" d="m3.5 8.5 3 3 6-7" />
75  </svg>
76);
77
78const Chevron = () => (
79  <svg width="16" height="16" viewBox="0 0 16 16" aria-hidden="true" focusable="false">
80    <path fill="none" stroke="currentColor" strokeWidth="1.8" strokeLinecap="round" strokeLinejoin="round" d="m3.5 6 4.5 4.5L12.5 6" />
81  </svg>
82);
83
84const Cross = ({ size = 16 }: { size?: number }) => (
85  <svg width={size} height={size} viewBox="0 0 16 16" aria-hidden="true" focusable="false">
86    <path fill="none" stroke="currentColor" strokeWidth="1.8" strokeLinecap="round" d="M4 4l8 8M12 4l-8 8" />
87  </svg>
88);
89
90const ErrorGlyph = () => (
91  <svg width="14" height="14" viewBox="0 0 16 16" aria-hidden="true" focusable="false">
92    <path fill="currentColor" d="M5 1h6l4 4v6l-4 4H5l-4-4V5z" />
93    <path fill="var(--surface)" d="M7.2 4h1.6v5H7.2zM7.2 10.4h1.6V12H7.2z" />
94  </svg>
95);
96
97const defaultEmpty = (query: string): ReactNode => (query.trim() ? `No match for “${query.trim()}”. Check the spelling, or clear the box to see every option.` : "Nothing to choose from yet.");
98
99// Options with a `group` are listed under that heading, in the order each heading first
100// appears; the rest come first, with no heading. With no group anywhere the list is flat.
101function grouped(items: ComboboxOption[]): ComboboxOption[] | Group[] {
102  if (!items.some((i) => i.group)) return items;
103  const out: Group[] = [];
104  const plain = items.filter((i) => !i.group);
105  if (plain.length) out.push({ value: "", items: plain });
106  for (const item of items) {
107    if (!item.group) continue;
108    let g = out.find((x) => x.value === item.group);
109    if (!g) {
110      g = { value: item.group, items: [] };
111      out.push(g);
112    }
113    g.items.push(item);
114  }
115  return out;
116}
117
118function Option({ item }: { item: ComboboxOption }) {
119  return (
120    <Base.Item key={item.value} value={item} disabled={item.disabled} className="cap-option">
121      <span className="cap-option-label">{item.label}</span>
122      <Base.ItemIndicator className="cap-option-indicator">
123        <Check />
124      </Base.ItemIndicator>
125    </Base.Item>
126  );
127}
128
129// The popup: the shared popover surface around the shared listbox, with the loading and
130// empty messages in Base UI's own regions so a change is announced.
131function Popup({ isGrouped, loading, loadingText, empty, container, anchor, multiple }: { isGrouped: boolean; loading: boolean; loadingText: string; empty: ReactNode; container?: HTMLElement | null; anchor?: RefObject<HTMLElement | null>; multiple: boolean }) {
132  return (
133    <Base.Portal container={container ?? undefined}>
134      <Base.Positioner className="cap-combobox-positioner" sideOffset={4} align="start" anchor={anchor}>
135        <Base.Popup className="cap-popover cap-combobox-popup" data-flush="">
136          <Base.Status className="cap-combobox-status">
137            {loading ? (
138              <>
139                <span className="cap-combobox-spinner" aria-hidden="true" />
140                {loadingText}
141              </>
142            ) : null}
143          </Base.Status>
144          <Base.Empty className="cap-listbox-empty cap-combobox-empty">{loading ? null : empty}</Base.Empty>
145          <Base.List className="cap-listbox cap-combobox-list" data-controlled="" data-selection={multiple ? "multi" : "single"}>
146            {isGrouped
147              ? (group: Group) => (
148                  <Base.Group key={group.value || "none"} items={group.items} className="cap-listbox-group">
149                    {group.value ? <Base.GroupLabel className="cap-listbox-label">{group.value}</Base.GroupLabel> : null}
150                    <Base.Collection>{(item: ComboboxOption) => <Option key={item.value} item={item} />}</Base.Collection>
151                  </Base.Group>
152                )
153              : (item: ComboboxOption) => <Option key={item.value} item={item} />}
154          </Base.List>
155        </Base.Popup>
156      </Base.Positioner>
157    </Base.Portal>
158  );
159}
160
161function Field({ label, labelId, inputId, required, help, helpId, error, errorId, children }: { label: string; labelId: string; inputId: string; required: boolean; help?: ReactNode; helpId: string; error?: ReactNode; errorId: string; children: ReactNode }) {
162  return (
163    <div className="cap-combobox" data-cap="combobox">
164      <label className="cap-combobox-label" id={labelId} htmlFor={inputId}>
165        {label}
166        {required && " (required)"}
167      </label>
168      {help != null && (
169        <p className="cap-combobox-help" id={helpId}>
170          {help}
171        </p>
172      )}
173      {children}
174      {error != null && (
175        <p className="cap-combobox-error" id={errorId}>
176          <ErrorGlyph />
177          {error}
178        </p>
179      )}
180    </div>
181  );
182}
183
184// One combobox: a labelled text box that filters a list, where only a listed value can be
185// chosen. Typed text that matches nothing is not kept: when the list closes, the box shows
186// the chosen value's label again (or nothing).
187export function Combobox(props: ComboboxProps) {
188  const { label, items, placeholder, emptyText, loading = false, loadingText = "Loading", help, error, disabled = false, required = false, name, container, defaultOpen, defaultInputValue, clearable = false } = props;
189  const autoId = useId();
190  const inputId = props.id ?? `${autoId}-input`;
191  const helpId = `${autoId}-help`;
192  const labelId = `${autoId}-label`;
193  const errorId = `${autoId}-error`;
194
195  const [own, setOwn] = useState<string | null>(props.defaultValue ?? null);
196  const current = props.value !== undefined ? props.value : own;
197  const selected = items.find((i) => i.value === current) ?? null;
198
199  // The input's text is held here so that unlisted text never outlives the open list.
200  const [query, setQuery] = useState<string>(defaultInputValue ?? selected?.label ?? "");
201  const chosen = useRef<ComboboxOption | null>(selected);
202  chosen.current = selected;
203  const open = useRef<boolean>(defaultOpen ?? false);
204
205  // Items that arrive after the value (loading, then loaded) bring the chosen label with
206  // them. Skipped on mount, so defaultInputValue stands.
207  const mounted = useRef(false);
208  useEffect(() => {
209    if (!mounted.current) {
210      mounted.current = true;
211      return;
212    }
213    if (!open.current) setQuery(selected?.label ?? "");
214  }, [selected?.label]);
215
216  const list = useMemo(() => grouped(items), [items]);
217  const isGrouped = items.some((i) => i.group);
218  const describedBy = [help != null ? helpId : "", error != null ? errorId : ""].filter(Boolean).join(" ") || undefined;
219  const empty = typeof emptyText === "function" ? emptyText(query) : (emptyText ?? defaultEmpty(query));
220
221  return (
222    <Field label={label} labelId={labelId} inputId={inputId} required={required} help={help} helpId={helpId} error={error} errorId={errorId}>
223      <Base.Root<ComboboxOption, false>
224        items={list}
225        value={selected}
226        onValueChange={(item: ComboboxOption | null) => {
227          chosen.current = item;
228          setQuery(item?.label ?? "");
229          if (props.value === undefined) setOwn(item?.value ?? null);
230          props.onValueChange?.(item?.value ?? null);
231        }}
232        inputValue={query}
233        onInputValueChange={(next: string) => setQuery(next)}
234        onOpenChange={(next: boolean) => {
235          open.current = next;
236          if (!next) setQuery(chosen.current?.label ?? "");
237        }}
238        isItemEqualToValue={(a: ComboboxOption, b: ComboboxOption) => a.value === b.value}
239        itemToStringLabel={(item: ComboboxOption) => item.label}
240        itemToStringValue={(item: ComboboxOption) => item.value}
241        disabled={disabled}
242        required={required}
243        name={name}
244        defaultOpen={defaultOpen}
245      >
246        <Base.InputGroup className="cap-combobox-group">
247          <Base.Input id={inputId} className="cap-combobox-input" aria-labelledby={labelId} placeholder={placeholder} aria-invalid={error != null ? true : undefined} aria-describedby={describedBy} autoComplete="off" />
248          {clearable && (
249            <Base.Clear className="cap-combobox-clear" aria-label={`Clear ${label}`}>
250              <Cross />
251            </Base.Clear>
252          )}
253          <Base.Trigger className="cap-combobox-trigger" aria-label={`Show ${label} options`}>
254            <Chevron />
255          </Base.Trigger>
256        </Base.InputGroup>
257        <Popup isGrouped={isGrouped} loading={loading} loadingText={loadingText} empty={empty} container={container} multiple={false} />
258      </Base.Root>
259    </Field>
260  );
261}
262
263// Several values: each chosen option is a chip in the box with its own remove button, and
264// the input follows the chips. The list stays open after a choice, so more can be added.
265export function ComboboxMultiple(props: ComboboxMultipleProps) {
266  const { label, items, placeholder, emptyText, loading = false, loadingText = "Loading", help, error, disabled = false, required = false, name, container, defaultOpen, defaultInputValue } = props;
267  const autoId = useId();
268  const inputId = props.id ?? `${autoId}-input`;
269  const helpId = `${autoId}-help`;
270  const labelId = `${autoId}-label`;
271  const errorId = `${autoId}-error`;
272  const anchor = useRef<HTMLDivElement | null>(null);
273
274  const { creatable = false, createLabel = (text: string) => `Create “${text}”` } = props;
275  const [own, setOwn] = useState<string[]>(props.defaultValues ?? []);
276  const current = props.values !== undefined ? props.values : own;
277  // Tags made by typing: they are not in `items`, so they are kept here (or come back in
278  // `values`, which are shown as chips whether or not they are listed).
279  const [made, setMade] = useState<ComboboxOption[]>([]);
280  const known = useMemo(() => {
281    const out = [...items];
282    for (const m of made) if (!out.some((i) => i.value === m.value)) out.push(m);
283    if (creatable) for (const v of current) if (!out.some((i) => i.value === v)) out.push({ value: v, label: v });
284    return out;
285  }, [items, made, creatable, current]);
286  const selected = useMemo(() => current.map((v) => known.find((i) => i.value === v)).filter((i): i is ComboboxOption => !!i), [current, known]);
287  const [query, setQuery] = useState(defaultInputValue ?? "");
288
289  const typed = tidy(query);
290  const makeable = creatable && typed !== "" && !known.some((i) => i.label.toLowerCase() === typed.toLowerCase());
291  const options = useMemo(() => (makeable ? [{ value: `${MAKE}${typed}`, label: createLabel(typed) }, ...known] : known), [makeable, typed, known, createLabel]);
292  const list = useMemo(() => grouped(options), [options]);
293  const isGrouped = options.some((i) => i.group);
294  const describedBy = [help != null ? helpId : "", error != null ? errorId : ""].filter(Boolean).join(" ") || undefined;
295  const empty = typeof emptyText === "function" ? emptyText(query) : (emptyText ?? defaultEmpty(query));
296
297  return (
298    <Field label={label} labelId={labelId} inputId={inputId} required={required} help={help} helpId={helpId} error={error} errorId={errorId}>
299      <Base.Root<ComboboxOption, true>
300        multiple
301        items={list}
302        value={selected}
303        onValueChange={(next: ComboboxOption[]) => {
304          const values: string[] = [];
305          const fresh: ComboboxOption[] = [];
306          for (const i of next) {
307            if (!i.value.startsWith(MAKE)) {
308              values.push(i.value);
309              continue;
310            }
311            const text = i.value.slice(MAKE.length);
312            if (!values.includes(text)) values.push(text);
313            fresh.push({ value: text, label: text });
314          }
315          if (fresh.length) {
316            setMade((m) => [...m, ...fresh.filter((f) => !m.some((x) => x.value === f.value))]);
317            setQuery("");
318          }
319          if (props.values === undefined) setOwn(values);
320          props.onValuesChange?.(values);
321        }}
322        inputValue={query}
323        onInputValueChange={(next: string) => setQuery(next)}
324        autoHighlight={creatable}
325        isItemEqualToValue={(a: ComboboxOption, b: ComboboxOption) => a.value === b.value}
326        itemToStringLabel={(item: ComboboxOption) => (item.value.startsWith(MAKE) ? typed : item.label)}
327        itemToStringValue={(item: ComboboxOption) => item.value}
328        disabled={disabled}
329        required={required}
330        name={name}
331        defaultOpen={defaultOpen}
332      >
333        <Base.Chips className="cap-combobox-chips" ref={anchor} data-disabled={disabled ? "" : undefined}>
334          <Base.Value>
335            {(value: ComboboxOption[]) => (
336              <Fragment>
337                {value.map((item) => (
338                  <Base.Chip key={item.value} className="cap-combobox-chip">
339                    {item.label}
340                    <Base.ChipRemove className="cap-combobox-chip-remove" aria-label={`Remove ${item.label}`}>
341                      <Cross size={12} />
342                    </Base.ChipRemove>
343                  </Base.Chip>
344                ))}
345                <Base.Input id={inputId} className="cap-combobox-input" aria-labelledby={labelId} placeholder={value.length ? undefined : placeholder} aria-invalid={error != null ? true : undefined} aria-describedby={describedBy} autoComplete="off" />
346              </Fragment>
347            )}
348          </Base.Value>
349        </Base.Chips>
350        <Popup isGrouped={isGrouped} loading={loading} loadingText={loadingText} empty={empty} container={container} anchor={anchor} multiple />
351      </Base.Root>
352    </Field>
353  );
354}