Skip to content
Browse documentation
whisk/ui

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.

Coming from another library?
Use 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.

Choose a region for this deployment.
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

PropTypeDefaultDescription
optionsreadonly ComboboxOption[]noneProvide a bounded, host-owned list with unique nonempty values. Options may have a label, group, description, disabled state, and decorative startElement or suffix.
valuestringnoneControl the committed value. Do not provide defaultValue at the same time. An unknown value displays no committed label.
defaultValuestringnoneInitialize the committed value for an uncontrolled Combobox.
onValueChange(value: string) => voidnoneRuns when an enabled option is committed with Enter or click, not while someone types a query.
placeholderstringSearch optionsGive the editable query a concise search prompt.
namestringnoneName the hidden native select used for form submission.
formstringnoneAssociate the hidden native select with a form by ID.
requiredbooleanfalseRequire a committed option through the hidden native select.
sizesm | md | lgmdSet the editable input size.
variantfilled | outline | flushedfilledChoose the input frame treatment.
optionSizesm | md | lgsizeUse a different size for option rows when necessary.
disabledbooleanfalsePrevent editing and selection while retaining the current value.
readOnlybooleanfalseShow the committed value without allowing edits or opening the list.
invalidbooleanfalseExpose invalid state; Field can supply it with an error message.
placementtop | bottombottomChoose where the list opens.
noResultsMessagestringNo options match your search. Try another term.Explain that the local search has no match and suggest a next step.
footerActionComboboxFooterActionnoneAdd one real button after the listbox. It is not an option and arrow keys do not reach it.

Shared props

PropSupportedNotes
as / asChildNoCombobox owns its editable input, hidden native select, and listbox structure.
Style propsNoCombobox exposes semantic form and appearance props instead of the shared style-prop surface. See Style props.
className / styleYesApplied to the editable input.
refYesForwards to the editable input.
Native HTML attributesYesNative input attributes are forwarded to the editable input, except Combobox-owned value, query, and ARIA attributes.

ComboboxOption fields

PropTypeDefaultDescription
valuestringnoneUnique, nonempty submitted value.
labelstringnoneVisible and announced option name.
disabledbooleanfalseKeep an unavailable option visible but prevent selection.
groupstringnoneName a meaningful option group.
descriptionstringnoneAdd supporting option detail.
startElementReactNodenoneDecorative leading content; never an interactive control.
suffixReactNodenoneDecorative trailing content; include essential meaning in label or description.

ComboboxFooterAction fields

PropTypeDefaultDescription
labelstringnoneVisible name for the host-owned action.
onClick() => voidnoneHandle the action outside option selection.
positionscroll | stickyscrollKeep the action after scrolling options or pinned below them.
disabledbooleanfalsePrevent the action while it is unavailable.
startElementReactNodenoneAdd decorative, noninteractive leading action content.
suffixReactNodenoneAdd decorative, noninteractive trailing action content.

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.