Dropdown Menu

Displays a menu to the user, such as a set of actions or functions, triggered by a button.

Anatomy

<DropdownMenu>
  <DropdownMenuTrigger />
  <DropdownMenuContent>
    <DropdownMenuLabel />
    <DropdownMenuSeparator />
    <DropdownMenuItem />
    <DropdownMenuSub>
      <DropdownMenuSubTrigger />
      <DropdownMenuSubContent>
        <DropdownMenuItem />
      </DropdownMenuSubContent>
    </DropdownMenuSub>
  </DropdownMenuContent>
</DropdownMenu>

Usage

To display a dropdown menu, compose <DropdownMenu>, <DropdownMenuTrigger>, <DropdownMenuContent>, and one or more of <DropdownMenuItem>.

import { Button } from "stylus-ui/Button";
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuLabel,
  DropdownMenuSeparator,
  DropdownMenuSub,
  DropdownMenuSubContent,
  DropdownMenuSubTrigger,
  DropdownMenuTrigger,
} from "stylus-ui/DropdownMenu";
import {
  faAngleDown,
  faArrowRightFromBracket,
  faCreditCard,
  faKeyboard,
  faPlus,
  faQuestionCircle,
  faSliders,
  faTrash,
  faUser,
} from "@fortawesome/pro-regular-svg-icons";

export default () => (
  <DropdownMenu>
    <DropdownMenuTrigger asChild>
      <Button variant="secondary">Open Menu</Button>
    </DropdownMenuTrigger>
    <DropdownMenuContent>
      <DropdownMenuLabel variant="title">Menu Title</DropdownMenuLabel>
      <DropdownMenuSeparator />
      <DropdownMenuItem icon={faUser} showShortcut shortcutText="⌘K">
        Profile
      </DropdownMenuItem>
      <DropdownMenuItem icon={faCreditCard} showShortcut shortcutText="⌘B">
        Billing
      </DropdownMenuItem>
      <DropdownMenuSub>
        <DropdownMenuSubTrigger icon={faSliders}>
          Settings
        </DropdownMenuSubTrigger>
        <DropdownMenuSubContent>
          <DropdownMenuItem icon={faArrowRightFromBracket}>
            Transfer account
          </DropdownMenuItem>
          <DropdownMenuItem variant="destructive" icon={faTrash}>
            Delete account
          </DropdownMenuItem>
        </DropdownMenuSubContent>
      </DropdownMenuSub>
      <DropdownMenuItem icon={faKeyboard}>Keyboard shortcuts</DropdownMenuItem>
      <DropdownMenuItem icon={faPlus} showTag disabled>
        New Team
      </DropdownMenuItem>
      <DropdownMenuItem icon={faQuestionCircle}>Support</DropdownMenuItem>
      <DropdownMenuSeparator />
      <DropdownMenuItem
        icon={faArrowRightFromBracket}
        showShortcut
        shortcutText="esc"
      >
        Log Out
      </DropdownMenuItem>
    </DropdownMenuContent>
  </DropdownMenu>
);

Checkboxes

To display a multiselect dropdown with checkboxes, use <DropdownMenuCheckboxItem> instead of <DropdownMenuItem>.

import { Button } from "stylus-ui/Button";
import {
  DropdownMenu,
  DropdownMenuTrigger,
  DropdownMenuContent,
  DropdownMenuCheckboxItem,
} from "stylus-ui/DropdownMenu";
import { useState } from "react";

export default () => {
  const [isHighContrastChecked, setIsHighContrastChecked] = useState(true);
  const [isReduceMotionChecked, setIsReduceMotionChecked] = useState(false);
  return (
    <DropdownMenu>
      <DropdownMenuTrigger asChild>
        <Button variant="secondary" dropdown>
          Accessibility
        </Button>
      </DropdownMenuTrigger>
      <DropdownMenuContent>
        <DropdownMenuCheckboxItem
          checked={isHighContrastChecked}
          onCheckedChange={setIsHighContrastChecked}
        >
          Enable High Contrast
        </DropdownMenuCheckboxItem>
        <DropdownMenuCheckboxItem
          checked={isReduceMotionChecked}
          onCheckedChange={setIsReduceMotionChecked}
        >
          Reduce Motion
        </DropdownMenuCheckboxItem>
      </DropdownMenuContent>
    </DropdownMenu>
  );
};

Radio group

To display a radio button group, use <DropdownMenuRadioItem> and wrap the items in <DropdownMenuRadioGroup>.

import { Button } from "stylus-ui/Button";
import {
  DropdownMenu,
  DropdownMenuTrigger,
  DropdownMenuContent,
  DropdownMenuRadioGroup,
  DropdownMenuRadioItem,
} from "stylus-ui/DropdownMenu";
import { useState } from "react";
import { faGrid, faGrid4, faGrid5 } from "@fortawesome/pro-regular-svg-icons";

export default () => {
  const [selectedValue, setSelectedValue] = useState("default");
  return (
    <DropdownMenu>
      <DropdownMenuTrigger asChild>
        <Button variant="secondary" dropdown>
          Density
        </Button>
      </DropdownMenuTrigger>
      <DropdownMenuContent>
        <DropdownMenuRadioGroup
          value={selectedValue}
          onValueChange={setSelectedValue}
        >
          <DropdownMenuRadioItem value="default" icon={faGrid}>
            Default
          </DropdownMenuRadioItem>
          <DropdownMenuRadioItem value="comfortable" icon={faGrid4}>
            Comfortable
          </DropdownMenuRadioItem>
          <DropdownMenuRadioItem value="compact" icon={faGrid5}>
            Compact
          </DropdownMenuRadioItem>
        </DropdownMenuRadioGroup>
      </DropdownMenuContent>
    </DropdownMenu>
  );
};

Submenus

To display a nested menu, compose <DropdownMenuSub>, <DropdownMenuSubTrigger>, <DropdownMenuSubContent>, and one or more of <DropdownMenuItem> within <DropdownMenuContent>.

import { Button } from "stylus-ui/Button";
import {
  DropdownMenu,
  DropdownMenuTrigger,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuSub,
  DropdownMenuSubTrigger,
  DropdownMenuSubContent,
} from "stylus-ui/DropdownMenu";

export default () => (
  <DropdownMenu>
    <DropdownMenuTrigger asChild>
      <Button variant="secondary" dropdown>
        Settings
      </Button>
    </DropdownMenuTrigger>
    <DropdownMenuContent>
      <DropdownMenuItem>Profile</DropdownMenuItem>
      <DropdownMenuItem>Billing</DropdownMenuItem>
      <DropdownMenuItem>Team</DropdownMenuItem>
      <DropdownMenuItem>Subscription</DropdownMenuItem>
      <DropdownMenuSub>
        <DropdownMenuSubTrigger>Theme</DropdownMenuSubTrigger>
        <DropdownMenuSubContent>
          <DropdownMenuItem>Light</DropdownMenuItem>
          <DropdownMenuItem>Dark</DropdownMenuItem>
        </DropdownMenuSubContent>
      </DropdownMenuSub>
    </DropdownMenuContent>
  </DropdownMenu>
);

API Reference

`DropdownMenu`

Displays a menu to the user, such as a set of actions or functions, triggered by a button.

`defaultOpen`

boolean

`dir`

"ltr" | "rtl"

`modal`

boolean

`onOpenChange`

(open: boolean) => void

`open`

boolean

`DropdownMenuTrigger`

The button that toggles the dropdown menu. By default, the DropdownMenu.Content will position itself against the trigger.

`asChild`

boolean

`DropdownMenuGroup`

Used to group multiple DropdownMenuItems.

`asChild`

boolean

`DropdownMenuPortal`

When used, portals the content part into the body.

`container`

null | Element | DocumentFragment

Specify a container element to portal the content into.

`forceMount`

true

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

`DropdownMenuSub`

Contains all the parts of a submenu.

`defaultOpen`

boolean

`onOpenChange`

(open: boolean) => void

`open`

boolean

`DropdownMenuRadioGroup`

Used to group multiple DropdownMenuRadioItems.

`asChild`

boolean

`onValueChange`

(value: string) => void

`value`

string

`DropdownMenuSubContent`

The component that pops out when a submenu is open. Must be rendered inside DropdownMenuSub.

`alignOffset`

number

`arrowPadding`

number

`asChild`

boolean

`avoidCollisions`

boolean

`collisionBoundary`

null | Element | Boundary[]

`collisionPadding`

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

`forceMount`

true

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

`hideWhenDetached`

boolean

`loop`

boolean = false

Whether keyboard navigation should loop around

`onEscapeKeyDown`

(event: KeyboardEvent) => void

`onFocusOutside`

(event: FocusOutsideEvent) => void

`onInteractOutside`

(event: PointerDownOutsideEvent | FocusOutsideEvent) => void

`onPointerDownOutside`

(event: PointerDownOutsideEvent) => void

`sideOffset`

number = 6

`sticky`

"partial" | "always"

`updatePositionStrategy`

"always" | "optimized"

`DropdownMenuContent`

The component that pops out when the dropdown menu is open.

`align`

"center" | "end" | "start"

`alignOffset`

number

`arrowPadding`

number

`asChild`

boolean

`avoidCollisions`

boolean

`collisionBoundary`

null | Element | Boundary[]

`collisionPadding`

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

`container`

HTMLElement

DOM node to portal the content into.

`forceMount`

true

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

`hideWhenDetached`

boolean

`isLoading`

boolean = false

When true, shows a skeleton placeholder instead of children.

`loop`

boolean = false

Whether keyboard navigation should loop around

`onCloseAutoFocus`

(event: Event) => void

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

`onEscapeKeyDown`

(event: KeyboardEvent) => void

`onFocusOutside`

(event: FocusOutsideEvent) => void

`onInteractOutside`

(event: PointerDownOutsideEvent | FocusOutsideEvent) => void

`onPointerDownOutside`

(event: PointerDownOutsideEvent) => void

`side`

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

`sideOffset`

number = 6

`sticky`

"partial" | "always"

`theme`

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

Background and text theme for the menu panel.

`updatePositionStrategy`

"always" | "optimized"

`DropdownMenuSubTrigger`

An item that opens a submenu. Must be rendered inside DropdownMenuSub.

`asChild`

boolean

`disabled`

boolean

`icon`

IconDefinition

`textValue`

string

`DropdownMenuLabel`

Used to render a label. It won’t be focusable using arrow keys.

`asChild`

boolean

`variant`

"label" | "title"

`DropdownMenuItem`

The component that contains the dropdown menu items.

`asChild`

boolean

`avatarProps`

AvatarProps & RefAttributes<HTMLDivElement>

`childrenClassName`

string

`disabled`

boolean

`icon`

IconDefinition

`iconClassName`

string

`onSelect`

(event: Event) => void

`shortcutText`

string

`showAvatar`

boolean

`showShortcut`

boolean

`showTag`

boolean

`subtext`

string

`subtextProps`

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

`tagComponent`

ReactNode

`textValue`

string

`variant`

"default" | "destructive"

`DropdownMenuCheckboxItem`

An item that can be controlled and rendered like a checkbox.

`asChild`

boolean

`avatarProps`

AvatarProps & RefAttributes<HTMLDivElement>

`checked`

false | true | "indeterminate"

`childrenClassName`

string

`disabled`

boolean

`icon`

IconDefinition

`iconClassName`

string

`onCheckedChange`

(checked: boolean) => void

`onSelect`

(event: Event) => void

`shortcutText`

string

`showAvatar`

boolean

`showShortcut`

boolean

`showTag`

boolean

`subtext`

string

`subtextProps`

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

`tagComponent`

ReactNode

`textValue`

string

`variant`

"default" | "destructive"

`DropdownMenuRadioItem`

An item that can be controlled and rendered like a radio.

`value`

Required

string

`asChild`

boolean

`avatarProps`

AvatarProps & RefAttributes<HTMLDivElement>

`childrenClassName`

string

`disabled`

boolean

`icon`

IconDefinition

`iconClassName`

string

`onSelect`

(event: Event) => void

`shortcutText`

string

`showAvatar`

boolean

`showShortcut`

boolean

`showTag`

boolean

`subtext`

string

`subtextProps`

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

`tagComponent`

ReactNode

`textValue`

string

`variant`

"default" | "destructive"

`DropdownMenuSeparator`

Used to visually separate items in the dropdown menu.

`asChild`

boolean