Dropdown Menu

Overview

The DropdownMenu component provides a way to create customizable dropdown menus. It can render submenus and show item various indicators.

It can be composed with several subcomponents such as DropdownMenu.Root, DropdownMenu.Trigger, DropdownMenu.Content, DropdownMenu.Header, DropdownMenu.Footer, DropdownMenu.Separator, DropdownMenu.Group and DropdownMenu.Item to offer a structured and customizable interface.

DropdownMenu.Item has such variations as AvatarItem, LogoItem, IconItem, IndicatorItem, CheckboxItem, and RadioItem to provide different types of items for different use cases.

Because DropdownMenu.Trigger uses asChild, any element can be the trigger — including a text Button. The Button keeps all of its themes and variants (here, variant="primary") while gaining the full dropdown menu functionality and item variations.

Usage

import { DropdownMenu } from "@harnessio/ui/components";

//...

return (
  <DropdownMenu.Root>
    <DropdownMenu.Trigger aria-label="options menu">
      <IconV2 name="more-horizontal" />
    </DropdownMenu.Trigger>

    <DropdownMenu.Content>
      <DropdownMenu.Item onSelect={onEdit}>Edit</DropdownMenu.Item>
      <DropdownMenu.Item onSelect={onDelete}>Delete</DropdownMenu.Item>
    </DropdownMenu.Content>
  </DropdownMenu.Root>
)

Anatomy

All parts of the DropdownMenu component can be imported and composed as required.

<DropdownMenu.Root>
  <DropdownMenu.Trigger />
  <DropdownMenu.Content>
    <DropdownMenu.Item />
    <DropdownMenu.Group>
      <DropdownMenu.Item />
    </DropdownMenu.Group>
    <DropdownMenu.Separator />
    <DropdownMenu.RadioGroup>
      <DropdownMenu.RadioItem />
    </DropdownMenu.RadioGroup>
    <DropdownMenu.Item>
      <DropdownMenu.AvatarItem />
      <DropdownMenu.LogoItem />
      <DropdownMenu.IconItem />
      <DropdownMenu.IndicatorItem />
      <DropdownMenu.CheckboxItem />
      <DropdownMenu.RadioItem />
    </DropdownMenu.Item>
  </DropdownMenu.Content>
</DropdownMenu.Root>

Properties

Properties

Root

The Root component serves as the main container for all dropdown menu elements. It requires both a Trigger and Content as children. It can be used in either a controlled or uncontrolled manner. When used in a controlled manner, you must pass in the open and onOpenChange props. When used in an uncontrolled manner, the open state is stored internally.

<DropdownMenu.Root
  open                    // [OPTIONAL] controlled open state
  onOpenChange={onChange} // [OPTIONAL] event handler called when the open state changes
  defaultOpen             // [OPTIONAL] default open state
  modal                   // [OPTIONAL] when set to true, interaction with outside elements
                          //            will be disabled and only menu content will be
                          //            visible to screen readers.
  dir                     // [OPTIONAL] reading direction of the dropdown
>
  {/* Trigger and Content */}
</DropdownMenu.Root>

Prop	Required	Default	Type
open	false	false	boolean
onOpenChange	false		(open: boolean) => void
defaultOpen	false	false	boolean
modal	false	true	boolean
dir	false		'ltr' | 'rtl'
children	true		ReactNode

Trigger

The Trigger component represents the button that triggers the dropdown menu.

Accessibility

The Trigger component renders as a button by default. It is recommended to include descriptive text inside the Trigger component to allow assistive technologies to announce the button with appropriate context. If the child is solely an icon, ensure that either aria-label is provided or descriptive text is included in a hidden element.

Example

<DropdownMenu.Trigger aria-label="options menu">
  <IconV2 name="more-horizontal" />
</DropdownMenu.Trigger>

Or

<DropdownMenu.Trigger>
  <IconV2 name="more-horizontal" />
  <span className="sr-only">Options menu</span>
</DropdownMenu.Trigger>

<DropdownMenu.Trigger
  className="my-class" // [OPTIONAL] custom class
  asChild              // [OPTIONAL] render the trigger as the child
  disabled             // [OPTIONAL] disable the trigger
>
  {/* Trigger content */}
</DropdownMenu.Trigger>

Prop	Required	Default	Type
className	false		string
asChild	false	false	boolean
disabled	false	false	boolean
children	true		ReactNode

Content

The Content component represents the dropdown menu content.

<DropdownMenu.Content
  className="my-class"      // [OPTIONAL] custom class
  sideOffset={4}            // [OPTIONAL] offset from the trigger
  align="start"             // [OPTIONAL] alignment relative to trigger
  alignOffset={0}           // [OPTIONAL] offset from align
  side="bottom"             // [OPTIONAL] preferred side of the trigger
>
  {/* Item, Group, Separator, RadioGroup, Header, Footer */}
</DropdownMenu.Content>

Prop	Required	Default	Type
className	false		string
sideOffset	false	4	number
align	false	'center'	'start' | 'center' | 'end'
alignOffset	false	0	number
side	false	'bottom'	'top' | 'right' | 'bottom' | 'left'
children	true		ReactNode

Item

The Item component represents a dropdown menu item.

<DropdownMenu.Item
  title="Item title"        // title of the item
  description="Description" // [OPTIONAL] description text
  label="Label"             // [OPTIONAL] right-aligned label
  shortcut="⌘K"             // [OPTIONAL] keyboard shortcut
  checkmark                 // [OPTIONAL] show checkmark icon
  prefix={<IconV2 />}         // [OPTIONAL] prefix element (icon, avatar, etc.)
  className="my-class"      // [OPTIONAL] custom class
  disabled                  // [OPTIONAL] disable the item
  onSelect={onSelect}       // [OPTIONAL] event handler called when the item is selected
  textValue="text"          // [OPTIONAL] text value for typeahead
  asChild                   // [OPTIONAL] render the item as the child
>
  {/* Optional nested items for submenu */}
</DropdownMenu.Item>

Prop	Required	Default	Type
title	true		ReactNode
description	false		string
label	false		string
shortcut	false		string
checkmark	false	false	boolean
prefix	false		ReactNode
tag	false		TagProps
className	false		string
disabled	false	false	boolean
onSelect	false		(event: Event) => void
textValue	false		string
asChild	false	false	boolean
children	false		ReactNode

Separator

The Separator component represents a visual divider between menu items.

<DropdownMenu.Separator
  className="my-class" // [OPTIONAL] custom class
/>

Prop	Required	Default	Type
className	false		string