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.
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:

Open the Insert Menu and go to Components.

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:

Select and remove the default Text inside the DropdownMenuItem.

Insert a Button inside the menu item.

Select the button and navigate to the Properties Panel.

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:

Remove the Text element in the DropdownMenuItem.

Insert a Button into the DropdownMenuItem.

In the Properties Panel, ensure the Behavior remains set to ‘Link’.

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:

Select the DropdownMenuItem component.

Navigate to the Properties Panel.

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:

Select the DropdownMenuItem.

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:

Add a DropdownMenuSub component inside the DropdownMenuContent.

Within the submenu, insert a DropdownMenuSubTrigger (the option that reveals the submenu).

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:

Select a DropdownMenuItem and insert a Row component from the Quick Add Strip.

Insert your desired Icon into the Row.

Insert a Text component into the Row.

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:

Select the Button within the DropdownMenuTrigger component.

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:

Remove the existing button within the DropdownMenuTrigger component.

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:

Select the DropdownMenuContent component.

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:

Select any component within a DropdownMenuItem.

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.