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:
  1. Insert a DropdownMenu component from the Library.
  1. 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:
  1. Add the DropdownMenuLinkItem component within your dropdown content or group.
  1. Select the DropdownMenuLinkItem and go to the Properties Panel.
  1. 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:
  1. Select the DropdownMenuItem and navigate to the Properties Panel.
  1. 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:
  1. Select the DropdownMenuItem.
  1. 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:
  1. Select a DropdownMenuItem and insert a Row component from the Quick Add Strip.
  1. Insert your desired Icon and a Text component into the Row.
  1. 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:
  1. Remove the existing button within the DropdownMenuTrigger component.
  1. 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.

Powered by Notaku