Combobox

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>.

Select Teammate

import { Button } from "stylus-ui/Button";
import {
  ComboBox,
  ComboBoxTrigger,
  ComboBoxContent,
  ComboBoxMenu,
  ComboBoxMenuItem,
} from "stylus-ui/ComboBox";
import { comboOptions } from "stylus-ui/ComboBox/constants.tsx";
import { faAngleDown } from "@fortawesome/pro-regular-svg-icons";

export default () => (
  <ComboBox>
    <ComboBoxTrigger asChild>
      <Button variant="secondary" dropdown>
        Select Teammate
      </Button>
    </ComboBoxTrigger>
    <ComboBoxContent>
      <ComboBoxMenu>
        {comboOptions.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}.

Select Teammate

import { Button } from "stylus-ui/Button";
import {
  ComboBox,
  ComboBoxTrigger,
  ComboBoxContent,
  ComboBoxLabel,
  ComboBoxMenu,
  ComboBoxMenuItem,
  ComboBoxSeparator,
} from "stylus-ui/ComboBox";
import {
  comboOptions,
  comboTimeframeOptions,
} from "stylus-ui/ComboBox/constants.tsx";
import { faUserPlus } from "@fortawesome/pro-regular-svg-icons";

export default () => (
  <ComboBox>
    <ComboBoxTrigger asChild>
      <Button variant="secondary" dropdown>
        Select Teammate
      </Button>
    </ComboBoxTrigger>
    <ComboBoxContent>
      <ComboBoxMenu>
        {comboOptions.map((option) => (
          <ComboBoxMenuItem {...option} key={option.value}>
            {option.label}
          </ComboBoxMenuItem>
        ))}
      </ComboBoxMenu>
      <ComboBoxSeparator />
      <ComboBoxLabel>Timeframe</ComboBoxLabel>
      <ComboBoxMenu isSearchable={false}>
        {comboTimeframeOptions.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.

Select Teammate

import { Button } from "stylus-ui/Button";
import {
  ComboBox,
  ComboBoxTrigger,
  ComboBoxContent,
  ComboBoxItem,
  ComboBoxMenu,
  ComboBoxMenuItem,
  ComboBoxSeparator,
} from "stylus-ui/ComboBox";
import { comboOptions } from "stylus-ui/ComboBox/constants.tsx";
import { faUserPlus } from "@fortawesome/pro-regular-svg-icons";

export default () => (
  <ComboBox>
    <ComboBoxTrigger asChild>
      <Button variant="secondary" dropdown>
        Select Teammate
      </Button>
    </ComboBoxTrigger>
    <ComboBoxContent>
      <ComboBoxMenu>
        {comboOptions.map((option) => (
          <ComboBoxMenuItem {...option} key={option.value}>
            {option.label}
          </ComboBoxMenuItem>
        ))}
      </ComboBoxMenu>
      <ComboBoxSeparator />
      <ComboBoxItem icon={faUserPlus}>Invite Teammates</ComboBoxItem>
    </ComboBoxContent>
  </ComboBox>
);

API Reference

ComboBox

Contains all the parts of the ComboBox.

Prop	Type	Default
children	ReactNode
defaultOpen	boolean
modal	boolean	false
onOpenChange	(open: boolean) => void
open	boolean

ComboBoxContent

The element that pops out when ComboBox is open.

Inherits properties from Radix Popover.Content and HTMLElement.

Prop	Type	Default
children	ReactNode
theme	"light""dark"	"dark"

ComboBoxItem

An interactive item which exists outside the scope of the menu and is not filterable.

Inherits properties from HTMLButtonElement.

Prop	Type	Default
avatarProps	React.ComponentProps<typeof Avatar>
children	ReactNode
childrenClassName	string
className	string
disabled	boolean
icon	IconDefinition
menuType	"checkbox""radio""item"
shortcutText	string
showAvatar	boolean
showShortcut	boolean
showTag	boolean
tagComponent	ReactNode
theme	"light""dark"	"dark"

ComboBoxLabel

A non-interactive label to provide a heading for a section of the ComboBox.

Prop	Type	Default
theme	"light""dark"	"dark"
variant	"title""label"	"label"

ComboBoxMenu

The element that contains all of the menu items and displays an input that can be used to filter them.

Prop	Type	Default
children	ReactNode
className	string
handleInputChange	(query: string) => void
isLoading	boolean	false
isSearchable	boolean	true
menuType	"checkbox""radio""item"	"radio"
noResultsText	string
onOptionSelect	(option: OptionType) => void
onValueChange	(value: OptionType[]) => void
placeholder	string	"Search"
scrollAreaChildren	ReactNode
theme	"light""dark"	"dark"

ComboBoxMenuItem

A single item within the filterable menu.

Prop	Type	Default
avatarProps	React.ComponentProps<typeof Avatar>
children	ReactNode
childrenClassName	string
className	string
disabled	boolean
icon	IconDefinition
menuType	"checkbox""radio""item"
shortcutText	string
showAvatar	boolean
showShortcut	boolean
showTag	boolean
tagComponent	ReactNode
theme	"light""dark"	"dark"

ComboBoxSeparator

A horizontal line to separate sections within the ComboBox.

ComboBoxTrigger

The button that, when clicked, toggles the ComboBox.

Inherits properties from HTMLButtonElement.

Prop	Type	Default
asChild	boolean	false