For AI agents: the complete documentation index is at llms.txt. Markdown versions are available by appending .md or sending Accept: text/markdown.
Square Banner
NewReflex Build On-Prem: A Secure Builder Running in Your Environment. Learn more
Square Banner
Reflex Logo
Docs Logo
Library

/

Overlay

/

Dropdown Menu

Dropdown Menu

A Dropdown Menu is a menu that offers a list of options that a user can select from. They are typically positioned near a button that will control their appearance and disappearance.

A Dropdown Menu is composed of a menu.root, a menu.trigger and a menu.content. The menu.trigger is the element that the user interacts with to open the menu. It wraps the element that will open the dropdown menu. The menu.content is the component that pops out when the dropdown menu is open.

The menu.item contains the actual dropdown menu items and sits under the menu.content. The shortcut prop is an optional shortcut command displayed next to the item text.

The menu.sub contains all the parts of a submenu. There is a menu.sub_trigger, which is an item that opens a submenu. It must be rendered inside a menu.sub component. The menu.sub_component is the component that pops out when a submenu is open. It must also be rendered inside a menu.sub component.

The menu.separator is used to visually separate items in a dropdown menu.

Expand

Events when the Dropdown Menu opens or closes

The on_open_change event, from the menu.root, is called when the open state of the dropdown menu changes. It is used in conjunction with the open prop, which is passed to the event handler.

Number of times Dropdown Menu opened or closed: 0

Dropdown Menu open: false

Expand

Opening a Dialog from Menu using State

Accessing an overlay component from within another overlay component is a common use case but does not always work exactly as expected.

The code below will not work as expected as because the dialog is within the menu and the dialog will only be open when the menu is open, rendering the dialog unusable.

In this example, we will show how to open a dialog box from a dropdown menu, where the menu will close and the dialog will open and be functional.

Expand

API Reference

rx.dropdown_menu.root

The Dropdown Menu Root Component.

Props

PropTypeDescription
default_open
bool

The open state of the dropdown menu when it is initially rendered. Use when you do not need to control its open state.

open
bool

The controlled open state of the dropdown menu. Must be used in conjunction with onOpenChange.

modal
bool

The modality of the dropdown menu. When set to true, interaction with outside elements will be disabled and only menu content will be visible to screen readers.

dir
"ltr""rtl"

The reading direction of submenus when applicable. If omitted, inherits globally from DirectionProvider or assumes LTR (left-to-right) reading mode.

Event Triggers

See the full list of default event triggers
TriggerDescription
on_open_changeFired when the open state changes.

rx.dropdown_menu.content

The Dropdown Menu Content component that pops out when the dropdown menu is open.

rx.menu.root(
rx.menu.trigger(
rx.button(
"Click to open Dropdown Menu",
color_scheme=props.get("color_scheme"),
variant=props.get("variant"),
),
),
rx.menu.content(
rx.menu.item("Edit", shortcut="⌘ E"),
rx.menu.item("Share"),
rx.menu.item("Delete", shortcut="⌘ ⌫", color="red"),
rx.menu.sub(
rx.menu.sub_trigger("More"),
rx.menu.sub_content(
rx.menu.item("Eradicate"),
rx.menu.item("Duplicate"),
rx.menu.item("Archive"),
),
),
size="1",
variant="solid",
color_scheme="tomato",
high_contrast=False,
align="start",
),
)
size
variant
color_scheme
high_contrast
align

Props

PropTypeDescription
size
"1""2"

Dropdown Menu Content size "1" - "2".

variant
"solid""soft"

Variant of Dropdown Menu Content: "solid" | "soft".

color_scheme
"tomato""red""ruby""crimson""pink""plum""purple""violet""iris""indigo""blue""cyan""teal""jade""green""grass""brown""orange""sky""mint""lime""yellow""amber""gold""bronze""gray"

Override theme color for Dropdown Menu Content.

high_contrast
bool

Renders the Dropdown Menu Content in higher contrast.

as_child
bool

Change the default rendered element for the one passed as a child, merging their props and behavior.

loop
bool

When True, keyboard navigation will loop from last item to first, and vice versa.

force_mount
bool

Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.

side
"top""right""bottom""left"

The preferred side of the trigger to render against when open. Will be reversed when collisions occur and avoid_collisions is enabled.The position of the tooltip.

side_offset
Union[float, int]

The distance in pixels from the trigger.

align
"start""center""end"

The preferred alignment against the trigger. May change when collisions occur.

align_offset
Union[float, int]

An offset in pixels from the "start" or "end" alignment options.

avoid_collisions
bool

When true, overrides the side and align preferences to prevent collisions with boundary edges.

collision_padding
Union[float, int, dict]

The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object, for example: { "top": 20, "left": 20 }.

sticky
"partial""always"

The sticky behavior on the align axis. "partial" will keep the content in the boundary as long as the trigger is at least partially in the boundary whilst "always" will keep the content in the boundary regardless.

hide_when_detached
bool

Whether to hide the content when the trigger becomes fully occluded.

Event Triggers

See the full list of default event triggers
TriggerDescription
on_close_auto_focusFired when the dialog is closed.
on_escape_key_downFired when the escape key is pressed.
on_pointer_down_outsideFired when the pointer is down outside the dialog.
on_focus_outsideFired when focus moves outside the dialog.
on_interact_outsideFired when the pointer interacts outside the dialog.

rx.dropdown_menu.trigger

The button that toggles the dropdown menu.

Props

PropTypeDescription
as_child
bool

Change the default rendered element for the one passed as a child, merging their props and behavior.

Event Triggers

See the full list of default event triggers

rx.dropdown_menu.item

The Dropdown Menu Item Component.

rx.menu.root(
rx.menu.trigger(
rx.button(
"Click to open Dropdown Menu",
color_scheme=props.get("color_scheme"),
variant=props.get("variant"),
),
),
rx.menu.content(
rx.menu.item("Edit", shortcut="⌘ E",
color_scheme="tomato",
disabled=False,
),
rx.menu.item("Share",
color_scheme="tomato",
disabled=False,
),
rx.menu.item("Delete", shortcut="⌘ ⌫", color="red",
color_scheme="tomato",
disabled=False,
),
rx.menu.sub(
rx.menu.sub_trigger("More"),
rx.menu.sub_content(
rx.menu.item("Eradicate",
color_scheme="tomato",
disabled=False,
),
rx.menu.item("Duplicate",
color_scheme="tomato",
disabled=False,
),
rx.menu.item("Archive",
color_scheme="tomato",
disabled=False,
),
),
),
),
)
color_scheme
disabled

Props

PropTypeDescription
color_scheme
"tomato""red""ruby""crimson""pink""plum""purple""violet""iris""indigo""blue""cyan""teal""jade""green""grass""brown""orange""sky""mint""lime""yellow""amber""gold""bronze""gray"

Override theme color for Dropdown Menu Item.

shortcut
str

Shortcut to render a menu item as a link.

as_child
bool

Change the default rendered element for the one passed as a child, merging their props and behavior.

disabled
bool

When true, prevents the user from interacting with the item.

text_value
str

Optional text used for typeahead purposes. By default the typeahead behavior will use the .textContent of the item. Use this when the content is complex, or you have non-textual content inside.

Event Triggers

See the full list of default event triggers
TriggerDescription
on_selectFired when the item is selected.

rx.dropdown_menu.separator

Dropdown Menu Separator Component. Used to visually separate items in the dropdown menu.

Props

No component specific props

Event Triggers

See the full list of default event triggers

rx.dropdown_menu.sub_content

The component that pops out when a submenu is open. Must be rendered inside DropdownMenuSub.

Props

PropTypeDescription
as_child
bool

Change the default rendered element for the one passed as a child, merging their props and behavior.

loop
bool

When True, keyboard navigation will loop from last item to first, and vice versa.

force_mount
bool

Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.

side_offset
Union[float, int]

The distance in pixels from the trigger.

align_offset
Union[float, int]

An offset in pixels from the "start" or "end" alignment options.

avoid_collisions
bool

When true, overrides the side and align preferences to prevent collisions with boundary edges.

collision_padding
Union[float, int, dict]

The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object, for example: { "top": 20, "left": 20 }.

sticky
"partial""always"

The sticky behavior on the align axis. "partial" will keep the content in the boundary as long as the trigger is at least partially in the boundary whilst "always" will keep the content in the boundary regardless.

hide_when_detached
bool

Whether to hide the content when the trigger becomes fully occluded.

Event Triggers

See the full list of default event triggers
TriggerDescription
on_escape_key_downFired when the escape key is pressed.
on_pointer_down_outsideFired when the pointer is down outside the dialog.
on_focus_outsideFired when focus moves outside the dialog.
on_interact_outsideFired when the pointer interacts outside the dialog.
Built with Reflex