Combobox
Search and choose from a larger option set.
Overview
Combobox lets people type to filter a finite, local list, then commit one existing option. Clicking or typing opens the list; the typed query is temporary, and only a committed option becomes the submitted value.
options, not children or ComboboxItem. Use onValueChange, not onChange; Combobox has no free-text, creatable, async-options, or query-control API.Use when
The user needs to filter and choose from a finite set of options.
Use instead
Use Select for a short list that does not need search, or TextInput when any text value is valid.
Usage
import { Combobox, Field } from "@smoothie-framework/whisk-react";
<Field label="Assignee">
<Combobox
name="assignee"
placeholder="Search people"
options={[
{ value: "maya", label: "Maya Chen" },
{ value: "aria", label: "Aria Patel" },
]}
/>
</Field>Examples
Variants
Choose the input treatment that fits the surrounding form.
import { Combobox, Field, FieldGroup } from "@smoothie-framework/whisk-react";
const people = [
{ value: "maya", label: "Maya Chen" },
{ value: "aria", label: "Aria Patel" },
];
<FieldGroup>
<Field label="Filled"><Combobox variant="filled" defaultValue="maya" options={people} /></Field>
<Field label="Outline"><Combobox variant="outline" defaultValue="maya" options={people} /></Field>
<Field label="Flushed"><Combobox variant="flushed" defaultValue="maya" options={people} /></Field>
</FieldGroup>Sizes
Choose the combobox size that matches the surrounding form density.
import { Combobox, Field, FieldGroup } from "@smoothie-framework/whisk-react";
const people = [
{ value: "maya", label: "Maya Chen" },
{ value: "aria", label: "Aria Patel" },
];
<FieldGroup>
<Field label="Small"><Combobox size="sm" defaultValue="maya" options={people} /></Field>
<Field label="Medium"><Combobox size="md" defaultValue="maya" options={people} /></Field>
<Field label="Large"><Combobox size="lg" defaultValue="maya" options={people} /></Field>
</FieldGroup>Groups
Group related options when their names help scanning. Descriptions and leading icons explain each option without changing its value.
import { BranchIcon, CloudIcon, SparksIcon } from "@smoothie-framework/whisk-react/icons";
import { Combobox, Field } from "@smoothie-framework/whisk-react";
<Field label="Environment">
<Combobox
defaultValue="production"
options={[
{
value: "production",
label: "Production",
group: "Deployments",
description: "Customer traffic",
startElement: <CloudIcon size="sm" />,
},
{
value: "staging",
label: "Staging",
group: "Deployments",
description: "Pre-release checks",
startElement: <BranchIcon size="sm" />,
},
{
value: "preview",
label: "Preview",
group: "Development",
description: "Pull request builds",
startElement: <SparksIcon size="sm" />,
},
]}
/>
</Field>Footer action
Use a footer action for a related task that is not a selectable option, such as creating a repository.
import { Combobox, Field } from "@smoothie-framework/whisk-react";
function createRepository() {
// Open the repository creation flow.
}
<Field label="Repository">
<Combobox
placeholder="Search repositories"
options={[
{ value: "framework", label: "Framework" },
{ value: "website", label: "Website" },
]}
footerAction={{ label: "Create repository", onClick: createRepository }}
/>
</Field>No results
Use a clear message that suggests a next step when the local options do not match the query.
import { Combobox, Field } from "@smoothie-framework/whisk-react";
<Field label="Repository">
<Combobox
placeholder="Search repositories"
noResultsMessage="No repositories match. Try another name."
options={[
{ value: "framework", label: "Framework" },
{ value: "website", label: "Website" },
]}
/>
</Field>Forms
Use react-hook-form with Controller because Combobox commits a string through value and onValueChange.
import { Controller, useForm } from "react-hook-form";
import { Box, Button, Combobox, Field, Stack } from "@smoothie-framework/whisk-react";
type AssignmentValues = { assignee: string };
export function AssignmentForm() {
const { control, handleSubmit } = useForm<AssignmentValues>({
defaultValues: { assignee: "" },
});
const onSubmit = (values: AssignmentValues) => {
// Send values to the application-owned assignment flow.
};
return (
<Box as="form" noValidate onSubmit={handleSubmit(onSubmit)}>
<Stack gap={3}>
<Controller
name="assignee"
control={control}
rules={{ required: "Choose an assignee." }}
render={({ field, fieldState }) => (
<Field label="Assignee" required error={fieldState.error?.message}>
<Combobox
name={field.name}
required
value={field.value}
onValueChange={field.onChange}
onBlur={field.onBlur}
options={[
{ value: "maya", label: "Maya Chen" },
{ value: "aria", label: "Aria Patel" },
]}
/>
</Field>
)}
/>
<Button type="submit">Assign</Button>
</Stack>
</Box>
);
}Disabled
Use disabled when the whole choice is unavailable. The current value remains readable.
import { Combobox, Field } from "@smoothie-framework/whisk-react";
<Field disabled label="Assignee">
<Combobox defaultValue="maya" options={[
{ value: "maya", label: "Maya Chen" },
{ value: "aria", label: "Aria Patel" },
]} />
</Field>Read-only
Use readOnly when the committed choice must stay visible but cannot be edited.
import { Combobox, Field } from "@smoothie-framework/whisk-react";
<Field label="Assignee">
<Combobox
readOnly
defaultValue="maya"
options={[
{ value: "maya", label: "Maya Chen" },
{ value: "aria", label: "Aria Patel" },
]}
/>
</Field>Disabled option
Keep an unavailable choice visible when people need to understand what cannot be selected.
import { Combobox, Field } from "@smoothie-framework/whisk-react";
<Field label="Repository">
<Combobox
placeholder="Search repositories"
options={[
{ value: "framework", label: "Framework" },
{ value: "billing", label: "Billing API", disabled: true, description: "Access is required." },
{ value: "website", label: "Website" },
]}
/>
</Field>Invalid
Let Field pass its invalid state and visible error to the Combobox after validation.
import { Combobox, Field } from "@smoothie-framework/whisk-react";
<Field label="Deployment region" error="Choose a region for this deployment.">
<Combobox
required
placeholder="Search regions"
options={[
{ value: "eu-west", label: "Europe West" },
{ value: "us-east", label: "US East" },
]}
/>
</Field>Controlled value
Use value and onValueChange when application state owns the committed choice.
import { useState } from "react";
import { Combobox, Field } from "@smoothie-framework/whisk-react";
export function AssigneePicker() {
const [assignee, setAssignee] = useState("maya");
return (
<Field label="Assignee">
<Combobox
value={assignee}
onValueChange={setAssignee}
options={[
{ value: "maya", label: "Maya Chen" },
{ value: "aria", label: "Aria Patel" },
]}
/>
</Field>
);
}Props
Component props
Shared props
ComboboxOption fields
ComboboxFooterAction fields
Accessibility
Give the input a visible Field label or accessible name. Combobox manages the editable combobox and listbox relationship: Arrow Up and Arrow Down move the active option, Enter commits it, Escape dismisses the list, and Tab keeps normal focus order. The query never creates an arbitrary value. Do not put links or buttons inside options; option adornments must be decorative. Use Field to connect a description, required state, and error message.
Content guidance
Name the category in the label, not the search interaction. Option labels should be recognizable on their own, and the no-results message should say what the user can try next.