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.
      • 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. Open the Insert Menu and go to Components.
  1. Click or drag the DropdownMenu to your desired location on the page.
💡
Pro tip
Quickly duplicate dropdown menu items in the composition by selecting DropdownMenuItem and pressing Cmd + D.

Guides

Performing Actions on Selection

To trigger an action when a menu item is selected:
  1. Select and remove the default Text inside the DropdownMenuItem.
  1. Insert a Button inside the menu item.
  1. Select the button and navigate to the Properties Panel.
  1. In the Properties Panel:
      • Change the Behavior property from the default ‘Link’ to ‘Button'.
      • Set the desired onClick action.

Routing

If a menu item should navigate the user to another page:
  1. Remove the Text element in the DropdownMenuItem.
  1. Insert a Button into the DropdownMenuItem.
  1. In the Properties Panel, ensure the Behavior remains set to ‘Link’.
  1. Enter the destination URL in the href field.

Disabled Items

You can disable certain dropdown items to prevent user interaction. This is useful when an action isn’t available yet.
To disable a dropdown item:
  1. Select the DropdownMenuItem component.
  1. Navigate to the Properties Panel.
  1. Set the disabled property to true.

Keeping the Menu Open on Selection

By default, the menu closes when an item is selected. If you wish to keep the menu open:
  1. Select the DropdownMenuItem.
  1. In the Properties Panel, set the closeOnSelect property to false.

Separators

Separators help organize menu items into distinct groups. To use separators in your dropdown, insert a DropdownMenuSeparator between related DropdownMenuItem components.

Submenus

A dropdown can contain nested menus to help organize complex options without overwhelming the user. To add a submenu to your dropdown:
  1. Add a DropdownMenuSub component inside the DropdownMenuContent.
  1. Within the submenu, insert a DropdownMenuSubTrigger (the option that reveals the submenu).
  1. Inside DropdownMenuSub, add a DropdownMenuSubContent with additional DropdownMenuItem elements.

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 into the Row.
  1. Insert a Text component into the Row.
  1. Adjust the icon’s placement before or after the text.

Customizing the Dropdown Trigger

By default, the dropdown contains a button to trigger the dropdown, but you can style this button or replace it with another component.
For example, if you wanted a dark-themed trigger button, you would follow these steps:
  1. Select the Button within the DropdownMenuTrigger component.
  1. Open the Properties Panel and adjust the following:
      • Text Color: Set it to a light tone like #ecedee so it stands out.
      • Background: Choose a Color that fits your design (e.g., transparent).
      • Border: Set a width (e.g., 2px) and radius (e.g., 10px), and set the color to a muted shade like #756e6e.
To replace the button with a custom trigger:
  1. Remove the existing button within the DropdownMenuTrigger component.
  1. Insert your preferred component (e.g., an Avatar) into the trigger.

Customizing the Dropdown Content Style

You can easily style the dropdown content through the Properties Panel. For example, if you wanted to create a dark-themed dropdown content area, you would do the following:
  1. Select the DropdownMenuContent component.
  1. In the Properties Panel, configure these settings:
      • Padding: Set to a value like 0.625rem to ensure ample spacing around the items.
      • Width: Specify a width, such as 12.5rem, for a consistent layout.
      • Background Color: Change the background to a dark shade (e.g., #18181b).
      • Text Color: Set to white for high contrast against the dark background.
      • Border Radius: Adjust to your desire (e.g., 10px) for softly rounded corners.

Customizing the Dropdown Items Style

You can also style individual dropdown items to match your design by customizing its content. For a dark theme, for example, follow these steps:
  1. Select any component within a DropdownMenuItem.
  1. In the Properties Panel:
      • Set the Border Radius to a value like 6px to give each item rounded corners.
      • Scroll up to the States field in the Properties Panel and click it.
      • Select the "highlighted" state. This state lets you define how the item looks when it’s hovered or focused.
      • Scroll back down to the Background Color setting and choose your desired color (e.g., #ffffff2b).

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.

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