DropdownMenu

The DropdownMenu component provides a way to create dropdown menus with various sub-components for customization.

Usage

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

//...

return (
  <DropdownMenu.Root>
    <DropdownMenu.Trigger aria-label="options menu">
      <Icon name="menu-dots" />
    </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.Item>
      <DropdownMenu.Shortcut />
    </DropdownMenu.Item>
    <DropdownMenu.Group>
      <DropdownMenu.Label />
      <DropdownMenu.Item />
    </DropdownMenu.Group>
    <DropdownMenu.Separator />
    <DropdownMenu.RadioGroup>
      <DropdownMenu.Label />
      <DropdownMenu.RadioItem />
    </DropdownMenu.RadioGroup>
    <DropdownMenu.Sub>
      <DropdownMenu.SubTrigger />
      <DropdownMenu.SubContent>
        <DropdownMenu.Item />
      </DropdownMenu.SubContent>
    </DropdownMenu.Sub>
  </DropdownMenu.Content>
</DropdownMenu.Root>

API Reference

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
  className="my-class"    // [OPTIONAL] custom class
  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.
>
  {/* Trigger and Content */}
</DropdownMenu.Root>

Prop	Required	Default	Type
className	false		string
open	false	false	boolean
onOpenChange	false		(open: boolean) => void
defaultOpen	false	false	boolean
modal	false	true	boolean
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">
  <Icon name="menu-dots" />
</DropdownMenu.Trigger>

Or

<DropdownMenu.Trigger>
  <Icon name="menu-dots" />
  <span className="sr-only">Options menu</span>
</DropdownMenu.Trigger>

<DropdownMenu.Trigger
  className="my-class" // [OPTIONAL] custom class
  insideSplitButton    // [OPTIONAL] whether the trigger is inside a split button
  asChild              // [OPTIONAL] render the trigger as the child
>
  {/* Trigger content */}
</DropdownMenu.Trigger>

Prop	Required	Default	Type
className	false		string
insideSplitButton	false	false	boolean
asChild	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 on the side
>
  {/* Item, Group, Separator, RadioGroup, Sub */}
</DropdownMenu.Content>

Prop	Required	Default	Type
className	false		string
sideOffset	false	4	number
children	true		ReactNode

Item

The Item component represents a dropdown menu item.

<DropdownMenu.Item
  className="my-class" // [OPTIONAL] custom class
  inset                // [OPTIONAL] whether the item is inset
  disabled             // [OPTIONAL] disable the item
  onSelect={onSelect}  // [OPTIONAL] event handler called when the item is selected
  textValue="text"     // [OPTIONAL] text value of the item to be used for when value is not suitable for typeahead search
  asChild              // [OPTIONAL] render the item as the child
>
  {/* Item content */}
</DropdownMenu.Item>

Prop	Required	Default	Type
className	false		string
inset	false	false	boolean
disabled	false		boolean
onSelect	false		(value: string) => void
textValue	false		string
asChild	false		boolean

Separator

The Separator component represents a dropdown menu separator.

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

Prop	Required	Default	Type
className	false		string

Sub

The Sub component can be used in 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.Sub
  open                    // [OPTIONAL] controlled open state
  onOpenChange={onChange} // [OPTIONAL] event handler called when the open state changes
  defaultOpen             // [OPTIONAL] default open state
>
  {/* SubTrigger and SubContent */}
</DropdownMenu.Sub>

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

SubTrigger

The SubTrigger component has the same props and behavior as the Trigger component above.

SubContent

The SubContent component has the same props and behavior as the Content component above.

Group

The Group component represents a dropdown menu group.

<DropdownMenu.Group
  className="my-class" // [OPTIONAL] custom class
>
  {/* Label, Item, etc */}
</DropdownMenu.Group>

Prop	Required	Default	Type
className	false		string
children	true		ReactNode

Label

The Label component represents a dropdown menu label.

<DropdownMenu.Label
  className="my-class" // [OPTIONAL] custom class
>
  {/* Label content */}
</DropdownMenu.Label>

Prop	Required	Default	Type
className	false		string
children	true		ReactNode

Shortcut

The Shortcut component visually represents the shortcut to press to activate the item.

Note

The use of the Shortcut component is purely decorative and does not register a keypress handler.

<DropdownMenu.Item>
  {/* Item content */}
  <DropdownMenu.Shortcut
    className="my-class" // [OPTIONAL] custom class
  >
    ⌘C
  </DropdownMenu.Shortcut>
</DropdownMenu.Item>

Prop	Required	Default	Type
children	true		ReactNode
className	false		string

CheckboxItem

The CheckboxItem component displays a checkbox next to the item. When the user interacts with the checkbox, the onCheckedChange prop is called. Setting the checked prop will set whether the checkbox is checked.

<DropdownMenu.CheckboxItem
  checked                    // [OPTIONAL] whether the checkbox is checked
  onCheckedChange={onChange} // [OPTIONAL] callback called when the checked state changes
  className="my-class"       // [OPTIONAL] custom class
>
  {/* Item content */}
</DropdownMenu.CheckboxItem>

Prop	Required	Default	Type
checked	false	false	boolean
onCheckedChange	false		(checked: boolean) => void
className	false		string
children	true		ReactNode

RadioGroup

The RadioGroup component groups together RadioItem components and controls the selected radio item.

<DropdownMenu.RadioGroup
  value                    // [OPTIONAL] the selected radio item
  onValueChange={onChange} // [OPTIONAL] callback called when the selected radio item changes
  className="my-class"     // [OPTIONAL] custom class
>
  {/* RadioItem */}
</DropdownMenu.RadioGroup>

Prop	Required	Default	Type
value	false		string
onValueChange	false		(value: string) => void
className	false		string
children	true		ReactNode

RadioItem

The RadioItem component displays a radio button next to the item. When the user interacts with the radio button, the the onValueChange prop of the parent RadioGroup component is called with the value from the clicked RadioItem.

<DropdownMenu.RadioGroup
  value={currentItem}
  onValueChange={setCurrentItem}
>
  <DropdownMenu.RadioItem
    value="item-1"       // value of the item
    className="my-class" // [OPTIONAL] custom class
  >
    {/* Item content */}
  </DropdownMenu.RadioItem>
</DropdownMenu.RadioGroup>

Prop	Required	Default	Type
value	true		string
className	false		string
children	true		ReactNode