Dropdown Menu

Overview

A dropdown menu displays a list of actions or options triggered by a button.

Features

Can be controlled or uncontrolled
Supports submenus with configurable reading direction
Supports items, labels, groups of items
Supports checkable items (single or multiple)
Customize side, alignment, offsets, collision handling
Focus is fully managed
Full keyboard navigation
Typeahead support
Optional modal or non-modal mode

Installation

npm install @radix-ui/react-dropdown-menu

Anatomy

Import all parts and piece them together.

import * as DropdownMenu from '@radix-ui/react-dropdown-menu';

export default () => (
  <DropdownMenu.Root>
    <DropdownMenu.Trigger />
    <DropdownMenu.Portal>
      <DropdownMenu.Content>
        <DropdownMenu.Label />
        <DropdownMenu.Item />

        <DropdownMenu.Group>
          <DropdownMenu.Item />
        </DropdownMenu.Group>

        <DropdownMenu.CheckboxItem>
          <DropdownMenu.ItemIndicator />
        </DropdownMenu.CheckboxItem>

        <DropdownMenu.RadioGroup>
          <DropdownMenu.RadioItem>
            <DropdownMenu.ItemIndicator />
          </DropdownMenu.RadioItem>
        </DropdownMenu.RadioGroup>

        <DropdownMenu.Sub>
          <DropdownMenu.SubTrigger />
          <DropdownMenu.Portal>
            <DropdownMenu.SubContent />
          </DropdownMenu.Portal>
        </DropdownMenu.Sub>

        <DropdownMenu.Separator />
        <DropdownMenu.Arrow />
      </DropdownMenu.Content>
    </DropdownMenu.Portal>
  </DropdownMenu.Root>
);

API Reference

Root

Contains all the parts of a dropdown menu.

boolean

The controlled open state of the dropdown menu. Must be used in conjunction with onOpenChange.

boolean

The open state of the dropdown menu when it is initially rendered. Use when you do not need to control its open state.

(open: boolean) => void

Event handler called when the open state of the dropdown menu changes.

'ltr' | 'rtl'

The reading direction of submenus when applicable. If omitted, inherits globally from DirectionProvider or assumes LTR (left-to-right) reading mode.

The modality of the dropdown menu. When set to true, interaction with outside elements will be disabled and only menu content will be visible to screen readers.

Trigger

The button that toggles the dropdown menu.

boolean

default:"false"

Change the default rendered element for the one passed as a child, merging their props and behavior.

Supports all standard HTML button attributes.

Portal

When used, portals the content part into the body.

HTMLElement

default:"document.body"

Specify a container element to portal the content into.

boolean

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

Content

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

boolean

default:"false"

Change the default rendered element for the one passed as a child, merging their props and behavior.

boolean

default:"false"

When true, keyboard navigation will loop from last item to first, and vice versa.

'top' | 'right' | 'bottom' | 'left'

default:"'bottom'"

The preferred side of the trigger to render against when open.

number

default:"0"

The distance in pixels from the trigger.

'start' | 'center' | 'end'

default:"'center'"

The preferred alignment against the trigger. May change when collisions occur.

number

default:"0"

An offset in pixels from the “start” or “end” alignment options.

boolean

default:"true"

When true, overrides the side and align preferences to prevent collisions with boundary edges.

Element | Element[]

default:"[]"

The element used as the collision boundary. By default this is the viewport.

number | Padding

default:"0"

The distance in pixels from the boundary edges where collision detection should occur.

'partial' | 'always'

default:"'partial'"

The sticky behavior on the align axis.

boolean

default:"false"

Whether to hide the content when the trigger becomes fully occluded.

(event: Event) => void

Event handler called when focus moves to the trigger after closing. It can be prevented by calling event.preventDefault.

(event: KeyboardEvent) => void

Event handler called when the escape key is down. It can be prevented by calling event.preventDefault.

(event: PointerDownOutsideEvent) => void

Event handler called when a pointer event occurs outside the bounds of the component. It can be prevented by calling event.preventDefault.

(event: PointerDownOutsideEvent | FocusOutsideEvent) => void

Event handler called when an interaction happens outside the bounds of the component. It can be prevented by calling event.preventDefault.

Item

The component that contains the dropdown menu items.

boolean

default:"false"

Change the default rendered element for the one passed as a child, merging their props and behavior.

boolean

default:"false"

When true, prevents the user from interacting with the item.

(event: Event) => void

Event handler called when the user selects an item (via mouse or keyboard). Calling event.preventDefault in this handler will prevent the dropdown menu from closing when selecting that item.

string

Optional text used for typeahead purposes. By default, the typeahead behavior will use the .textContent of the item. Use this when the content is complex, or you have non-textual content inside.

Group

Used to group multiple items. Use in conjunction with DropdownMenu.Label to ensure good accessibility via automatic labelling.

boolean

default:"false"

Change the default rendered element for the one passed as a child, merging their props and behavior.

Label

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

boolean

default:"false"

Change the default rendered element for the one passed as a child, merging their props and behavior.

CheckboxItem

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

boolean

default:"false"

Change the default rendered element for the one passed as a child, merging their props and behavior.

boolean | 'indeterminate'

The controlled checked state of the item. Must be used in conjunction with onCheckedChange.

(checked: boolean) => void

Event handler called when the checked state changes.

boolean

default:"false"

When true, prevents the user from interacting with the item.

(event: Event) => void

Event handler called when the user selects an item (via mouse or keyboard). Calling event.preventDefault in this handler will prevent the dropdown menu from closing when selecting that item.

string

Optional text used for typeahead purposes.

RadioGroup

Used to group multiple DropdownMenu.RadioItems.

boolean

default:"false"

Change the default rendered element for the one passed as a child, merging their props and behavior.

string

The value of the selected item in the group.

(value: string) => void

Event handler called when the value changes.

RadioItem

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

boolean

default:"false"

Change the default rendered element for the one passed as a child, merging their props and behavior.

string

required

The unique value of the item.

boolean

default:"false"

When true, prevents the user from interacting with the item.

(event: Event) => void

Event handler called when the user selects an item (via mouse or keyboard).

string

Optional text used for typeahead purposes.

ItemIndicator

Renders when the parent DropdownMenu.CheckboxItem or DropdownMenu.RadioItem is checked. You can style this element directly, or you can use it as a wrapper to put an icon into, or both.

boolean

default:"false"

Change the default rendered element for the one passed as a child, merging their props and behavior.

boolean

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

Separator

Used to visually separate items in the dropdown menu.

boolean

default:"false"

Change the default rendered element for the one passed as a child, merging their props and behavior.

Sub

Contains all the parts of a submenu.

boolean

The controlled open state of the submenu. Must be used in conjunction with onOpenChange.

boolean

The open state of the submenu when it is initially rendered. Use when you do not need to control its open state.

(open: boolean) => void

Event handler called when the open state of the submenu changes.

SubTrigger

An item that opens a submenu. Must be rendered inside DropdownMenu.Sub.

boolean

default:"false"

Change the default rendered element for the one passed as a child, merging their props and behavior.

boolean

default:"false"

When true, prevents the user from interacting with the item.

string

Optional text used for typeahead purposes.

SubContent

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

boolean

default:"false"

Change the default rendered element for the one passed as a child, merging their props and behavior.

boolean

default:"false"

When true, keyboard navigation will loop from last item to first, and vice versa.

(event: KeyboardEvent) => void

Event handler called when the escape key is down.

(event: PointerDownOutsideEvent) => void

Event handler called when a pointer event occurs outside the bounds of the component.

Arrow

An optional arrow element to render alongside the dropdown menu.

boolean

default:"false"

Change the default rendered element for the one passed as a child, merging their props and behavior.

number

default:"10"

The width of the arrow in pixels.

number

default:"5"

The height of the arrow in pixels.

Example

import * as DropdownMenu from '@radix-ui/react-dropdown-menu';

function DropdownMenuDemo() {
  return (
    <DropdownMenu.Root>
      <DropdownMenu.Trigger className="button">
        Options
      </DropdownMenu.Trigger>
      <DropdownMenu.Portal>
        <DropdownMenu.Content className="dropdown-menu-content">
          <DropdownMenu.Item className="dropdown-menu-item">
            New Tab
          </DropdownMenu.Item>
          <DropdownMenu.Item className="dropdown-menu-item">
            New Window
          </DropdownMenu.Item>
          <DropdownMenu.Separator className="dropdown-menu-separator" />
          <DropdownMenu.Item className="dropdown-menu-item">
            Settings
          </DropdownMenu.Item>
        </DropdownMenu.Content>
      </DropdownMenu.Portal>
    </DropdownMenu.Root>
  );
}

import { useState } from 'react';
import * as DropdownMenu from '@radix-ui/react-dropdown-menu';
import { CheckIcon } from '@radix-ui/react-icons';

function DropdownMenuWithSelections() {
  const [showBookmarks, setShowBookmarks] = useState(true);
  const [showUrls, setShowUrls] = useState(false);
  const [person, setPerson] = useState('pedro');

  return (
    <DropdownMenu.Root>
      <DropdownMenu.Trigger>View</DropdownMenu.Trigger>
      <DropdownMenu.Portal>
        <DropdownMenu.Content>
          <DropdownMenu.Label>View Options</DropdownMenu.Label>
          <DropdownMenu.CheckboxItem
            checked={showBookmarks}
            onCheckedChange={setShowBookmarks}
          >
            <DropdownMenu.ItemIndicator>
              <CheckIcon />
            </DropdownMenu.ItemIndicator>
            Show Bookmarks
          </DropdownMenu.CheckboxItem>
          <DropdownMenu.CheckboxItem
            checked={showUrls}
            onCheckedChange={setShowUrls}
          >
            <DropdownMenu.ItemIndicator>
              <CheckIcon />
            </DropdownMenu.ItemIndicator>
            Show Full URLs
          </DropdownMenu.CheckboxItem>
          
          <DropdownMenu.Separator />
          
          <DropdownMenu.Label>People</DropdownMenu.Label>
          <DropdownMenu.RadioGroup value={person} onValueChange={setPerson}>
            <DropdownMenu.RadioItem value="pedro">
              <DropdownMenu.ItemIndicator>
                <CheckIcon />
              </DropdownMenu.ItemIndicator>
              Pedro Duarte
            </DropdownMenu.RadioItem>
            <DropdownMenu.RadioItem value="colm">
              <DropdownMenu.ItemIndicator>
                <CheckIcon />
              </DropdownMenu.ItemIndicator>
              Colm Tuite
            </DropdownMenu.RadioItem>
          </DropdownMenu.RadioGroup>
        </DropdownMenu.Content>
      </DropdownMenu.Portal>
    </DropdownMenu.Root>
  );
}

import * as DropdownMenu from '@radix-ui/react-dropdown-menu';

function DropdownMenuWithSubmenu() {
  return (
    <DropdownMenu.Root>
      <DropdownMenu.Trigger>File</DropdownMenu.Trigger>
      <DropdownMenu.Portal>
        <DropdownMenu.Content>
          <DropdownMenu.Item>New File</DropdownMenu.Item>
          <DropdownMenu.Item>Save</DropdownMenu.Item>
          <DropdownMenu.Separator />
          <DropdownMenu.Sub>
            <DropdownMenu.SubTrigger>
              Export
            </DropdownMenu.SubTrigger>
            <DropdownMenu.Portal>
              <DropdownMenu.SubContent>
                <DropdownMenu.Item>PDF</DropdownMenu.Item>
                <DropdownMenu.Item>HTML</DropdownMenu.Item>
                <DropdownMenu.Item>Markdown</DropdownMenu.Item>
              </DropdownMenu.SubContent>
            </DropdownMenu.Portal>
          </DropdownMenu.Sub>
          <DropdownMenu.Separator />
          <DropdownMenu.Item>Close</DropdownMenu.Item>
        </DropdownMenu.Content>
      </DropdownMenu.Portal>
    </DropdownMenu.Root>
  );
}

import { useState } from 'react';
import * as DropdownMenu from '@radix-ui/react-dropdown-menu';

function ControlledDropdownMenu() {
  const [open, setOpen] = useState(false);

  return (
    <DropdownMenu.Root open={open} onOpenChange={setOpen}>
      <DropdownMenu.Trigger>
        {open ? 'Close' : 'Open'}
      </DropdownMenu.Trigger>
      <DropdownMenu.Portal>
        <DropdownMenu.Content>
          <DropdownMenu.Item onSelect={() => console.log('Edit')}>
            Edit
          </DropdownMenu.Item>
          <DropdownMenu.Item onSelect={() => console.log('Duplicate')}>
            Duplicate
          </DropdownMenu.Item>
          <DropdownMenu.Separator />
          <DropdownMenu.Item
            onSelect={() => {
              console.log('Delete');
              setOpen(false);
            }}
          >
            Delete
          </DropdownMenu.Item>
        </DropdownMenu.Content>
      </DropdownMenu.Portal>
    </DropdownMenu.Root>
  );
}

Accessibility

Adheres to the Menu Button WAI-ARIA design pattern and uses roving tabindex to manage focus movement among menu items.

Keyboard Interactions

Space - Opens the dropdown menu and activates items
Enter - Opens the dropdown menu and activates items
ArrowDown - When focus is on trigger, opens the dropdown menu. When open, moves focus to the next item
ArrowUp - Moves focus to the previous item
ArrowRight - Opens a submenu or moves focus to the next item in a submenu
ArrowLeft - Closes a submenu or moves to the parent menu
Esc - Closes the dropdown menu and moves focus to trigger

Overlays

Navigation

Forms

Layout

Data Display

Utilities

Overview

Features

Installation

Anatomy

API Reference

Root

Trigger

Portal

Content

Item

Group

Label

CheckboxItem

RadioGroup

RadioItem

ItemIndicator

Separator

Sub

SubTrigger

SubContent

Arrow

Example

Accessibility

Keyboard Interactions

​Overview

​Features

​Installation

​Anatomy

​API Reference

​Root

​Trigger

​Portal

​Content

​Item

​Group

​Label

​CheckboxItem

​RadioGroup

​RadioItem

​ItemIndicator

​Separator

​Sub

​SubTrigger

​SubContent

​Arrow

​Example

​Accessibility

​Keyboard Interactions

Overview

Features

Installation

Anatomy

API Reference

Root

Trigger

Portal

Content

Item

Group

Label

CheckboxItem

RadioGroup

RadioItem

ItemIndicator

Separator

Sub

SubTrigger

SubContent

Arrow

Example

Accessibility

Keyboard Interactions