Combobox

A React combobox and autocomplete on Base UI with filtering, multi select with a selected count, creatable options, and async server search.

Loading preview

Examples

Practical examples and common states for the same installable component.

Basic

Single-select combobox with client-side filtering.

examples/combobox-basic.tsx
"use client";
import * as React from "react";
import { Combobox } from "@/components/wensity/combobox";
const frameworkOptions = [
{ value: "nextjs", label: "Next.js" },
{ value: "remix", label: "Remix" },
{ value: "nuxt", label: "Nuxt" },
{ value: "sveltekit", label: "SvelteKit" },
{ value: "astro", label: "Astro" },
];
export function ComboboxBasic() {
const [value, setValue] = React.useState("nextjs");
return (
<Combobox
label="Framework"
placeholder="Search frameworks…"
value={value}
onValueChange={(next) =>
setValue(Array.isArray(next) ? (next[0] ?? "") : next)
}
options={frameworkOptions}
/>
);
}

Disabled

Combobox in a locked state - no input, no popup.

examples/combobox-disabled.tsx
import { Combobox } from "@/components/wensity/combobox";
export function ComboboxDisabled() {
return (
<Combobox
disabled
label="Region"
placeholder="Locked to primary region"
defaultValue="iad"
options={[
{ value: "iad", label: "US East" },
{ value: "fra", label: "Europe" },
]}
hint="Contact support to change region assignments."
/>
);
}

Error

Surfaces an inline validation message when required.

examples/combobox-error.tsx
"use client";
import * as React from "react";
import { Combobox } from "@/components/wensity/combobox";
const frameworkOptions = [
{ value: "nextjs", label: "Next.js" },
{ value: "remix", label: "Remix" },
{ value: "astro", label: "Astro" },
];
export function ComboboxError() {
const [value, setValue] = React.useState("");
const hasError = value.length === 0;
return (
<Combobox
required
label="Framework"
placeholder="Pick a framework"
value={value}
onValueChange={(next) =>
setValue(Array.isArray(next) ? (next[0] ?? "") : next)
}
options={frameworkOptions}
error={hasError ? "Choose a framework before continuing." : undefined}
/>
);
}

Async

Load or filter options from an external source.

examples/combobox-async.tsx
"use client";
import * as React from "react";
import { Combobox } from "@/components/wensity/combobox";
const frameworkOptions = [
{ value: "nextjs", label: "Next.js" },
{ value: "remix", label: "Remix" },
{ value: "astro", label: "Astro" },
{ value: "sveltekit", label: "SvelteKit" },
];
export function ComboboxAsync() {
const [query, setQuery] = React.useState("");
const [loading, setLoading] = React.useState(false);
const [options, setOptions] = React.useState(frameworkOptions);
const handleSearchChange = React.useCallback(
(nextQuery: string) => {
setQuery(nextQuery);
if (nextQuery !== query) setLoading(true);
},
[query],
);
React.useEffect(() => {
const timeout = window.setTimeout(() => {
setOptions(
frameworkOptions.filter((option) =>
option.label.toLowerCase().includes(query.toLowerCase()),
),
);
setLoading(false);
}, 400);
return () => window.clearTimeout(timeout);
}, [query]);
return (
<Combobox
label="Framework"
placeholder="Search frameworks…"
options={options}
loading={loading}
filter={false}
onSearchChange={handleSearchChange}
/>
);
}

Creatable

Create a new option when nothing matches the query.

examples/combobox-creatable.tsx
"use client";
import * as React from "react";
import { Combobox } from "@/components/wensity/combobox";
export function ComboboxCreatable() {
const [options, setOptions] = React.useState([
{ value: "design", label: "Design" },
{ value: "engineering", label: "Engineering" },
]);
return (
<Combobox
multiple
creatable
label="Teams"
placeholder="Search or create…"
options={options}
onCreateOption={(input) => {
const created = {
value: input.toLowerCase().replace(/\s+/g, "-"),
label: input,
};
setOptions((current) => [...current, created]);
return created;
}}
/>
);
}

Overview

Combobox is a React and Tailwind CSS combobox and autocomplete built on Base UI, in Next.js or any React app, for searchable selects, tag pickers, and filters. Typing filters options by label, value, and description, and multiple turns it into a multi select whose closed field reads like Design + 2 more beside a selected count. With creatable, a Create row adds whatever was typed as a new option, and onCreateOption lets you shape it first. Backspace in an empty field drops the last pick. For server search, set filter to false, pass loading, and fetch inside onSearchChange.

Installation

Run the following command

~/your-project
pnpm dlx wensity@latest add combobox

Usage

Import Combobox from @/components/wensity/combobox and render it anywhere in your React or Next.js app. The source lands in your own repo, so every prop, class and animation below is yours to edit.

app/example.tsx
import { Combobox } from "@/components/wensity/combobox";
export function ComboboxDemo() {
return (
<Combobox
multiple
label="Replication regions"
placeholder="Search regions to add…"
defaultValue={["fra", "sin"]}
emptySelectionLabel="No replication regions selected."
options={[
{ value: "iad", label: "US East" },
{ value: "fra", label: "Europe" },
{ value: "sin", label: "Asia Pacific" },
]}
/>
);
}

Props

PropTypeDefaultDescription
optionsComboboxOption[] | ComboboxGroup[]-Choices to render. Pass groups to get labelled sections.
valuestring | string[]-Controlled selection. An array when multiple is set.
defaultValuestring | string[]-Initial selection when uncontrolled.
onValueChange(value: string | string[]) => void-Called when the selection changes.
multiplebooleanfalseAllows selecting more than one option.
creatablebooleanfalseOffers to create an option from the current query when nothing matches.
onCreateOption(inputValue: string) => ComboboxOption | void-Called when the create affordance is chosen.
loadingbooleanfalseShows a loading state in the list, for async option sources.
onSearchChange(query: string) => void-Called as the query changes. Use for server-side search.
filterbooleantrueClient-side filtering. Set false when options come from onSearchChange.
labelReact.ReactNode-Field label above the trigger.
hintReact.ReactNode-Helper copy under the trigger.
errorReact.ReactNode-Error message under the trigger, with invalid styling applied.
status"default" | "error" | "success"-Drives the success and error visuals.
placeholderstring"Search…"Query input placeholder.
emptyMessageReact.ReactNode"No results found."Shown when the query matches nothing.
closeWhenAllSelectedbooleantrueCloses the list once every option is chosen in multiple mode.
comboboxSize"sm" | "md" | "lg""md"Trigger height and text size.
fullWidthbooleantrueStretches the trigger to fill its container.
  • Multi-Select Tag Input component preview

    Multi-Select Tag Input

    A tag input where pills pop in as you add them and slide out on remove, closing the gap without snapping the layout.

  • Gooey Search Bar component preview

    Gooey Search Bar

    A search circle stretches into a field, and results drip out below it. Ask Claude, ChatGPT, or Google in one keystroke.

  • Google-Style Search Bar component preview

    Google-Style Search Bar

    A Google AI Mode search bar with a rainbow that travels the rim, cycling typewriter prompts, and an inline Google wordmark.

  • AI Model Selector component preview

    AI Model Selector

    An AI model selector dropdown that scales out from its trigger and glides the selection pill to whichever model you pick.