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`

CombobBox content wrapper. It extends Radix’s PopoverContent and adds a theme prop.

`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"

`theme`

"light" | "dark" | "light" | "dark" = "dark"

Background and text theme for the dropdown panel.

`updatePositionStrategy`

"always" | "optimized"

`ComboBoxMenuItemBase`

Base component for ComboBox items. It can be used to display a list of options based off of menuType, icon, showAvatar, and avatarProps.

`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"

`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

`theme`

"light" | "dark" | "light" | "dark" = "dark"

`ComboBoxLabel`

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

`asChild`

boolean

`variant`

"label" | "title"