Dropdown Menu

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

Linking Menu Items to Pages

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 to true.

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 to false.

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’
align	`‘center’	‘start’	‘end’`
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’`
hideWhenDetached	`boolean`	`true`	Hides the menu if the trigger is detached from the DOM.
updatePositionStrategy	`‘always’	‘optimized’`	`‘optimized’`

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.