Combobox

An autocomplete input and command palette with a list of suggestions.

Anatomy

<Combobox>
  <ComboboxTrigger />
  <ComboboxContent>
    <ComboboxMenu>
      <ComboboxMenuItem />
    </ComboboxMenu>
    <ComboboxSeparator />
    <ComboboxLabel />
    <ComboboxItem />
  </ComboboxContent>
</Combobox>

Usage

To display a filterable list of menu items, compose <Combobox>, <ComboboxTrigger>, <ComboboxContent>, <ComboboxMenu>, and one or more of <ComboboxMenuItem>.

import { Button } from "stylus-ui/Button";
import {
  Combobox,
  ComboboxTrigger,
  ComboboxContent,
  ComboboxMenu,
  ComboboxMenuItem,
} from "stylus-ui/Combobox";

const options = [
  { value: 1, label: "John Doe" },
  { value: 2, label: "Jane Smith" },
  { value: 3, label: "Robert Johnson" },
  { value: 4, label: "Alice Williams" },
  { value: 5, label: "Charlie Brown" },
];

export default () => (
  <Combobox>
    <ComboboxTrigger asChild>
      <Button variant="secondary" dropdown>
        Select Teammate
      </Button>
    </ComboboxTrigger>
    <ComboboxContent>
      <ComboboxMenu>
        {options.map((option) => (
          <ComboboxMenuItem {...option} key={option.value}>
            {option.label}
          </ComboboxMenuItem>
        ))}
      </ComboboxMenu>
    </ComboboxContent>
  </Combobox>
);

Multiple menus

You can include more than one <ComboboxMenu> in the dropdown. When including multiple menus, it’s helpful to also include <ComboboxLabel> and <ComboboxSeparator>. To prevent a menu from displaying a search input, use isSearchable={false}.

import { Button } from "stylus-ui/Button";
import {
  Combobox,
  ComboboxTrigger,
  ComboboxContent,
  ComboboxLabel,
  ComboboxMenu,
  ComboboxMenuItem,
  ComboboxSeparator,
} from "stylus-ui/Combobox";

const teammates = [
  { value: 1, label: "John Doe" },
  { value: 2, label: "Jane Smith" },
  { value: 3, label: "Robert Johnson" },
  { value: 4, label: "Alice Williams" },
  { value: 5, label: "Charlie Brown" },
];

const timeframes = [
  { value: "last_7_days", label: "Last 7 Days" },
  { value: "last_30_days", label: "Last 30 Days" },
  { value: "last_3_months", label: "Last 3 Months" },
  { value: "last_12_months", label: "Last 12 Months" },
];

export default () => (
  <Combobox>
    <ComboboxTrigger asChild>
      <Button variant="secondary" dropdown>
        Select Teammate
      </Button>
    </ComboboxTrigger>
    <ComboboxContent>
      <ComboboxMenu>
        {teammates.map((option) => (
          <ComboboxMenuItem {...option} key={option.value}>
            {option.label}
          </ComboboxMenuItem>
        ))}
      </ComboboxMenu>
      <ComboboxSeparator />
      <ComboboxLabel>Timeframe</ComboboxLabel>
      <ComboboxMenu isSearchable={false}>
        {timeframes.map((option) => (
          <ComboboxMenuItem {...option} key={option.value}>
            {option.label}
          </ComboboxMenuItem>
        ))}
      </ComboboxMenu>
    </ComboboxContent>
  </Combobox>
);

Non-filterable actions

Add extra items outside the scope of menu filters by using <ComboboxItem>. Use a <ComboboxSeparator> to visually distinguish sections.

import { Button } from "stylus-ui/Button";
import {
  Combobox,
  ComboboxTrigger,
  ComboboxContent,
  ComboboxItem,
  ComboboxMenu,
  ComboboxMenuItem,
  ComboboxSeparator,
} from "stylus-ui/Combobox";
import { faUserPlus } from "@fortawesome/pro-regular-svg-icons";

const options = [
  { value: 1, label: "John Doe" },
  { value: 2, label: "Jane Smith" },
  { value: 3, label: "Robert Johnson" },
  { value: 4, label: "Alice Williams" },
  { value: 5, label: "Charlie Brown" },
];

export default () => (
  <Combobox>
    <ComboboxTrigger asChild>
      <Button variant="secondary" dropdown>
        Select Teammate
      </Button>
    </ComboboxTrigger>
    <ComboboxContent>
      <ComboboxMenu>
        {options.map((option) => (
          <ComboboxMenuItem {...option} key={option.value}>
            {option.label}
          </ComboboxMenuItem>
        ))}
      </ComboboxMenu>
      <ComboboxSeparator />
      <ComboboxItem icon={faUserPlus}>Invite Teammates</ComboboxItem>
    </ComboboxContent>
  </Combobox>
);

API Reference

`Combobox`

Displays an autocomplete input with a list of suggestions. The list of suggestions is displayed in a Popover and extends Radix’s Popover props.

`defaultOpen`

boolean

`modal`

boolean

`onOpenChange`

(open: boolean) => void

`open`

boolean

`ComboboxTrigger`

`asChild`

boolean

`ComboboxSeparator`

`asChild`

boolean

`ComboboxContent`

Combobox content wrapper.

`align`

"center" | "end" | "start"

`alignOffset`

number

`arrowPadding`

number

`asChild`

boolean

`avoidCollisions`

boolean

`children`

ReactNode

Content (e.g. ComboboxInput, ComboboxItem list).

`collisionBoundary`

null | Element | Boundary[]

`collisionPadding`

number | Partial<Record<"bottom" | "top" | "left" | "right", number>>

`container`

null | Element | DocumentFragment

`forceMount`

true

Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.

`hideWhenDetached`

boolean

`onCloseAutoFocus`

(event: Event) => void

Event handler called when auto-focusing on close. Can be prevented.

`onEscapeKeyDown`

(event: KeyboardEvent) => void

Event handler called when the escape key is down. Can be prevented.

`onFocusOutside`

(event: FocusOutsideEvent) => void

Event handler called when the focus moves outside of the DismissableLayer. Can be prevented.

`onInteractOutside`

(event: PointerDownOutsideEvent | FocusOutsideEvent) => void

Event handler called when an interaction happens outside the DismissableLayer. Specifically, when a pointerdown event happens outside or focus moves outside of it. Can be prevented.

`onOpenAutoFocus`

(event: Event) => void

Event handler called when auto-focusing on open. Can be prevented.

`onPointerDownOutside`

(event: PointerDownOutsideEvent) => void

Event handler called when the a pointerdown event happens outside of the DismissableLayer. Can be prevented.

`side`

"bottom" | "top" | "left" | "right"

`sideOffset`

number

`sticky`

"partial" | "always"

`updatePositionStrategy`

"always" | "optimized"

`ComboboxMenuItem`

Menu item for the Combobox. It can be used to display a list of options based off of menuType.

`value`

Required

string | number

`avatarProps`

AvatarProps & RefAttributes<HTMLDivElement>

`checked`

boolean = false

`childrenClassName`

string

`disabled`

boolean

`icon`

IconDefinition

`iconClassName`

string

`menuType`

`onItemKeyDown`

(e: KeyboardEvent<HTMLDivElement>, option: OptionType) => void

`onItemSelect`

(option: OptionType) => void

`shortcutText`

string

`showAvatar`

boolean

`showShortcut`

boolean

`showTag`

boolean

`subtext`

string

`subtextProps`

ClassAttributes<HTMLDivElement> & HTMLAttributes<HTMLDivElement> & { className?: string | undefined; }

`tagComponent`

ReactNode

`variant`

"default" | "destructive"

`ComboboxItem`

Item for the Combobox. It can be used to display a call to action or item that is outside of ComboboxMenu.

`avatarProps`

AvatarProps & RefAttributes<HTMLDivElement>

`childrenClassName`

string

`disabled`

boolean

`icon`

IconDefinition

`iconClassName`

string

`shortcutText`

string

`showAvatar`

boolean

`showShortcut`

boolean

`showTag`

boolean

`subtext`

string

`subtextProps`

ClassAttributes<HTMLDivElement> & HTMLAttributes<HTMLDivElement> & { className?: string | undefined; }

`tagComponent`

ReactNode

`variant`

"default" | "destructive"

`ComboboxMenu`

An autocomplete input and command palette with a list of suggestions.

`className`

string

`handleInputChange`

(query: string) => void

`isLoading`

boolean = false

`isSearchable`

boolean = true

`menuType`

`noResultsText`

string

`onOptionSelect`

(option: OptionType) => void

`onValueChange`

(value: OptionType[]) => void

`placeholder`

string = "Search"

`scrollAreaChildren`

ReactNode

`ComboboxLabel`

A label for a Combobox. It isn’t focusable.

`asChild`

boolean

`variant`

"label" | "title"