A Dropdown Menu component lets you display a list of actions or options to a user when triggered. It's useful for actions like navigation, settings, or filtering content.
Anatomy
A Dropdown Menu consists of the following elements:
- DropdownMenuTrigger – The clickable element that opens the dropdown.
- DropdownMenuContent – The container that displays the list of menu items.
- DropdownMenuGroup – This container groups related menu items together.
- DropdownMenuItem – An individual option that users can select.
- DropdownMenuLinkItem - A specialized menu item that functions as a link.
- DropdownMenuSeparator – A visual divider that separates sections of menu items.
- DropdownMenuSub – A container for nested submenus.
- DropdownMenuSubTrigger – The element that reveals a submenu when hovered or clicked.
- DropdownMenuSubContent – The container for submenu items.
Adding a Dropdown Menu
To add a Dropdown Menu to your project:
- Insert a DropdownMenu component from the Library.
- You can add or remove menu items within the Dropdown as needed. To add new items, either insert additional DropdownMenuItem or DropdownMenuLinkItem components from the Library, or duplicate an existing item.
Pro tip
Quickly duplicate a DropdownMenuItem or DropdownMenuLinkItem in the composition by selecting one and pressing
Cmd + D
(Mac) or Ctrl + D
(Windows).Guides
Routing
You can use the DropdownMenuLinkItem to navigate users to a specific URL. Here’s how to do that:
- Add the DropdownMenuLinkItem component within your dropdown content or group.
- Select the DropdownMenuLinkItem and go to the Properties Panel.
- Set the
href
property to the destination URL.
Disabled Item
You can disable dropdown items to prevent users from interacting with them.
To disable a dropdown item:
- Select the DropdownMenuItem and navigate to the Properties Panel.
- Set the
disabled
property totrue
.
Keeping the Menu Open on Selection
If you wish to keep the menu open when an item is selected:
- Select the DropdownMenuItem.
- In the Properties Panel, set the
closeOnSelect
property tofalse
.
Submenus
A dropdown can contain submenus to help organize complex options without overwhelming the user. You can add submenus from the Insert Menu.
Icons
Icons can help users quickly recognize menu items. To add icons in your dropdown menu:
- Select a DropdownMenuItem and insert a Row component from the Quick Add Strip.
- Insert your desired Icon and a Text component into the Row.
- Adjust the Row’s spacing and alignment in the Properties Panel to get a balanced layout.
Styling the Dropdown Trigger
The dropdown trigger uses a button to toggle the menu, which you can style to match your design.
The following video demonstrates styling a dropdown trigger button to have an outlined appearance.
Using a Custom Trigger
You can also replace the default button with a custom trigger. Here’s how to do that:
- Remove the existing button within the DropdownMenuTrigger component.
- Insert your preferred component (e.g., an Avatar) into the trigger.
Styling the Dropdown Content
You can fully customize the appearance of your dropdown menu, including the overall content container and individual menu items. All styling can be done through the Properties Panel.
Some customization options include:
- DropdownMenuContent: Adjust padding, width, background color, text color, and border-radius to create a cohesive look for your dropdown container.
- Menu Items: Customize the background color, text color, border radius, and spacing of individual menu items. Use the States field to style your items in different states (e.g.,
highlighted
).
The video below shows how to style your dropdown content and items to fit a dark-themed design.
Pro tip
Create and apply the same class to all menu items if you want to share similar styles.
Properties
DropdownMenu
Property | Type | Default | Description |
defaultOpen | boolean | false | The open state of the dropdown menu when it is initially rendered. Use when you do not need to control its open state. |
modal | boolean | - | When set to true , interactions with outside elements will be disabled and only menu content will be visible to screen readers. |
DropdownMenuContent
Property | Type | Default | Description |
sideOffset | number | 4 | The distance in pixels between the trigger and the menu content. |
portal | boolean | true | When set to true , the dropdown menu content will be rendered in a portal. |
loop | boolean | true | Allows keyboard navigation to loop through items from the start to the end. |
side | ‘top’ | ‘bottom’ | ‘left’ | ‘right' | ‘bottom’ | The side of the trigger where the menu will appear. |
align | ‘center’ | ‘start’ | ‘end’ | ‘start’ | How the menu content aligns relative to the trigger. |
alignOffset | number | 0 | Additional offset to fine-tune horizontal positioning. |
forceMount | boolean | false | Forces the menu content to be rendered even if not open. It can be useful for animations. |
onEscapeKeyDown | Action | - | Callback when the Escape key is pressed. |
onPointerDownOutside | Action | - | Callback when a click is detected outside the menu. |
onFocusOutside | Action | - | Callback when focus moves outside the menu. |
onInteractOutside | Action | - | Called when an interaction (pointer or focus event) happens outside the bounds of the component. |
onCloseAutoFocus | Action | - | Event handler called when auto-focusing on close (can be prevented) |
arrowPadding | number | - | Padding around the menu’s arrow indicator. |
avoidCollisions | boolean | true | Prevents the menu from colliding with the viewport boundaries. |
collisionBoundary | Element | - | Specifies elements that the menu should avoid overlapping. |
collisionPadding | number | 0 | Padding to add when avoiding collisions. |
sticky | ‘portal’ | ‘always’ | ‘portal’ | Determines how the menu content sticks to the trigger during scrolling. |
hideWhenDetached | boolean | true | Hides the menu if the trigger is detached from the DOM. |
updatePositionStrategy | ‘always’ | ‘optimized’ | ‘optimized’ | Determines how frequently the menu recalculates its position. |
DropdownMenuItem
Property | Type | Default | Description |
closeOnSelect | boolean | true | When set to true , will close the dropdown menu when a user selects the menu item. |
disabled | boolean | false | If true , prevents the user from interacting with the menu item. |
DropdownMenuLinkItem
Property | Type | Default | Description |
href | string | - | URL or path the link navigates to when clicked. |
rel | string | - | Specifies the relationship between the current page and the linked URL. Refer to MDN documentation for valid values. |
target | string | - | Specifies where to open the linked URL. Refer to MDN documentation for valid values. |
closeOnSelect | boolean | true | When set to true , will close the dropdown menu when a user selects the menu link item. |
disabled | boolean | false | If true , prevents the user from interacting with the link. |
DropdownMenuSub
Property | Type | Default | Description |
defaultOpen | boolean | false | The open state of the dropdown submenu when it is initially rendered. Use when you do not need to control its open state. |
DropdownMenuSubTrigger
Property | Type | Default | Description |
disabled | boolean | false | If true , prevents the user from interacting with the submenu trigger. |