Atoms / Combobox

Combobox

Pick one or several among many by typing. Options can come from a server, and the text can become one.

import { Combobox, type ComboboxOption } from "@forgeron/ui";
/01 → Single
import { Combobox } from "@forgeron/ui";

const countries = [
  { value: "fr", label: "France", hint: "FR" },
  { value: "de", label: "Germany", hint: "DE" },
  { value: "es", label: "Spain", hint: "ES" },
  { value: "it", label: "Italy", hint: "IT" },
  { value: "pt", label: "Portugal", hint: "PT" },
  { value: "nl", label: "Netherlands", hint: "NL" },
];

export default function Single() {
  return (
    <Combobox
      label="Country"
      options={countries}
      placeholder="Search a country"
      defaultValue="fr"
    />
  );
}
/02 → Multiple creatable
import { Combobox, type ComboboxOption } from "@forgeron/ui";
import { useState } from "react";

const labels: ComboboxOption[] = [
  { value: "bug", label: "bug" },
  { value: "docs", label: "documentation" },
  { value: "design", label: "design" },
  { value: "infra", label: "infrastructure" },
];

export default function MultipleCreatable() {
  const [chosen, setChosen] = useState<string[]>(["bug"]);
  const [options, setOptions] = useState(labels);
  return (
    <Combobox
      multiple
      label="Labels"
      placeholder="Add a label"
      options={options}
      value={chosen}
      onChange={setChosen}
      onCreate={(text) => {
        const made = { value: text.toLowerCase().replace(/\s+/g, "-"), label: text };
        setOptions((o) => [...o, made]);
        return made;
      }}
    />
  );
}
/03 → Async
import { Combobox, type ComboboxOption } from "@forgeron/ui";
import { useEffect, useState } from "react";

const people = [
  "Ada Lovelace",
  "Alan Turing",
  "Grace Hopper",
  "Linus Torvalds",
  "Margaret Hamilton",
];

// A stand-in for a server: answers after a short wait, with what matches.
const search = (query: string): Promise<ComboboxOption[]> =>
  new Promise((resolve) =>
    setTimeout(
      () =>
        resolve(
          people
            .filter((p) => p.toLowerCase().includes(query.toLowerCase()))
            .map((p) => ({ value: p.toLowerCase().replace(/\s/g, "."), label: p })),
        ),
      400,
    ),
  );

export default function Async() {
  const [query, setQuery] = useState("");
  // The answer remembers the question it belongs to: while they differ, the list is loading.
  const [answer, setAnswer] = useState<{ query: string; options: ComboboxOption[] } | null>(null);
  useEffect(() => {
    let live = true;
    search(query).then((options) => live && setAnswer({ query, options }));
    return () => {
      live = false;
    };
  }, [query]);
  return (
    <Combobox
      label="Assignee"
      placeholder="Search people"
      options={answer?.options ?? []}
      filter={false}
      loading={answer?.query !== query}
      onInputChange={setQuery}
    />
  );
}
API → Props
PropTypeDefaultDescription
labelstring—Names the control for assistive technology.
optionsComboboxOption[]—{ value, label, hint?, glyph?, disabled? }.
multiplebooleanfalseSeveral choices, shown as chips. Then value is string[].
value / defaultValuestring | null (string[] with multiple)—Controlled or not.
onChange(value) => void—On every change.
onInputChange(query: string) => void—Hears every key: ask a server, pass the answer as options.
filterbooleantruefalse when options are already filtered by the caller.
loadingboolean—Says so in the list.
onCreate(label) => ComboboxOption | void—Turns the text typed into a choice; adds a Create row.
emptyText / createLabelstring / (query) => string—The words of the empty and create rows.
clearablebooleantrueA button that removes the choice (single only).
placeholderstring—In the text box.
disabledboolean—Not editable.
id / aria-describedby / aria-invalidstring / string / boolean—From `Field`'s function form: the label, hint and error stay tied.
classNamestring—Extra classes.