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";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"
/>
);
}bug
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;
}}
/>
);
}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
| Prop | Type | Default | Description |
|---|---|---|---|
label | string | — | Names the control for assistive technology. |
options | ComboboxOption[] | — | { value, label, hint?, glyph?, disabled? }. |
multiple | boolean | false | Several choices, shown as chips. Then value is string[]. |
value / defaultValue | string | 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. |
filter | boolean | true | false when options are already filtered by the caller. |
loading | boolean | — | Says so in the list. |
onCreate | (label) => ComboboxOption | void | — | Turns the text typed into a choice; adds a Create row. |
emptyText / createLabel | string / (query) => string | — | The words of the empty and create rows. |
clearable | boolean | true | A button that removes the choice (single only). |
placeholder | string | — | In the text box. |
disabled | boolean | — | Not editable. |
id / aria-describedby / aria-invalid | string / string / boolean | — | From `Field`'s function form: the label, hint and error stay tied. |
className | string | — | Extra classes. |