Navigation Menu
A set of links with expandable panels for site navigation.
This demo runs the real GPUI component on WebGPU, which this browser does not expose.
Try Chrome or Edge 113+, or Safari 26+. In Firefox, enable dom.webgpu.enabled.
You can also run it natively: cargo run -p showcase navigation-menu
The demo failed to start in this browser.
You can run it natively instead: cargo run -p showcase navigation-menu
Live examples are not supported on most mobile browsers yet — open this page on a desktop or tablet to run the demo.
Recent phones with WebGPU may manage it (downloads ~18 MB):
#Anatomy
Import the component's parts and compose them under its root:
use base_gpui::navigation_menu::{
NavigationMenuArrow,
NavigationMenuBackdrop,
NavigationMenuContent,
NavigationMenuIcon,
NavigationMenuItem,
NavigationMenuLink,
NavigationMenuList,
NavigationMenuPopup,
NavigationMenuPortal,
NavigationMenuPositioner,
NavigationMenuRoot,
NavigationMenuTrigger,
NavigationMenuViewport,
};
NavigationMenuRoot::new()
.child(
NavigationMenuList::new()
.child(
NavigationMenuItem::new()
.child(
NavigationMenuContent::new(),
)
.child(
NavigationMenuTrigger::new()
.child(
NavigationMenuIcon::new(),
),
),
)
.child(
NavigationMenuLink::new(),
),
)
.child(
NavigationMenuPortal::new()
.child(
NavigationMenuBackdrop::new(),
)
.child(
NavigationMenuPositioner::new()
.child(
NavigationMenuArrow::new(),
)
.child(
NavigationMenuPopup::new()
.child(
NavigationMenuViewport::new(),
),
),
),
);
The anatomy is a structural overview. Parts with mutually exclusive modes may need separate instances; each part's section below documents its configuration.
#NavigationMenuRoot
Coordinates the component's state and supplies context to its child parts.
use base_gpui::navigation_menu::NavigationMenuRoot;
NavigationMenuRoot::new()
.id("example-id")
.default_value(None)
.value(None)
.delay(/* delay: Duration */)
.close_delay(/* close_delay: Duration */)
.orientation(/* orientation: NavigationMenuOrientation */)
.nested(true)
.aria_label("aria label")
.on_value_change(|/* callback arguments */| { /* handle change */ })
.on_open_change_complete(|/* callback arguments */| { /* handle change */ })
.style_with_state(|/* callback arguments */| { /* handle change */ });
#Builders
| Builder | Signature & description |
|---|---|
.new | pub fn new() -> SelfCreates a NavigationMenuRoot with its default configuration. |
.id | pub fn id(mut self, id: impl Into<ElementId>) -> Self
Sets the stable GPUI element identity. Use a unique value when multiple instances can appear in the same view. |
.child | pub fn child(mut self, child: impl Into<NavigationMenuChild<T>>) -> Self
Adds one typed child to this part. |
.children | pub fn children(mut self, children: impl IntoIterator<Item = impl Into<NavigationMenuChild<T>>>,) -> Self
Adds multiple typed children in iteration order. |
.child_any | pub fn child_any(mut self, child: impl IntoElement) -> Self
Adds one arbitrary renderable child to this part. |
.default_value | pub fn default_value(mut self, default_value: Option<T>) -> Self
Sets the initial value for uncontrolled state. Later user changes are retained by the component. |
.value | pub fn value(mut self, value: Option<T>) -> Self
Sets the current controlled value or the value represented by this part, depending on the part's role. |
.delay | pub fn delay(mut self, delay: Duration) -> Self
Sets the delay before the related transition or interaction begins. |
.close_delay | pub fn close_delay(mut self, close_delay: Duration) -> Self
Sets the delay before an open component closes after the closing interaction. |
.orientation | pub fn orientation(mut self, orientation: NavigationMenuOrientation) -> Self
Sets the component's horizontal or vertical orientation and corresponding keyboard behavior. |
.nested | pub fn nested(mut self, nested: bool) -> Self
Marks this root as nested inside another navigation menu's content (renders inline; style state reports |
.aria_label | pub fn aria_label(mut self, aria_label: impl Into<SharedString>) -> Self
Accessible label for the navigation landmark (non-nested roots only; nested roots carry no role). |
.on_value_change | pub fn on_value_change(mut self, on_value_change: impl Fn(Option<T>, &mut NavigationMenuValueChangeDetails, &mut Window, &mut App) + 'static,) -> Self
Registers a callback invoked when value change occurs. |
.on_open_change_complete | pub fn on_open_change_complete(mut self, on_open_change_complete: impl Fn(Option<T>, &NavigationMenuValueChangeDetails, &mut Window, &mut App) + 'static,) -> Self
Registers a callback invoked when open change complete occurs. |
.style_with_state | pub fn style_with_state(mut self, style: impl Fn(NavigationMenuRootStyleState, Div) -> Div + 'static,) -> Self
Styles the part from its current behavioral state while preserving separation between behavior and visual design. NavigationMenuRoot also supports the GPUI traits implemented in its source, such as standard styling or child composition. |
#NavigationMenuTrigger
Interactive control that opens, closes, or activates the component.
use base_gpui::navigation_menu::NavigationMenuTrigger;
NavigationMenuTrigger::new()
.disabled(true)
.is_disabled()
.aria_label("aria label")
.style_with_state(|/* callback arguments */| { /* handle change */ })
.wired(/* value: T */, /* focus_handle: FocusHandle */, 0, 0);
#Builders
| Builder | Signature & description |
|---|---|
.new | pub fn new() -> SelfCreates a NavigationMenuTrigger with its default configuration. |
.disabled | pub fn disabled(mut self, disabled: bool) -> Self
When true, prevents user interaction with this part. |
.is_disabled | pub fn is_disabled(&self) -> boolControls whether disabled behavior is enabled. |
.aria_label | pub fn aria_label(mut self, aria_label: impl Into<SharedString>) -> Self
Accessible name for the trigger button; pass one when the visible caption is not plain accessible text (no id-reference labelling exists). Render the visible caption with |
.child | pub fn child(mut self, child: impl Into<NavigationMenuTriggerChild<T>>) -> Self
Adds one typed child to this part. |
.child_any | pub fn child_any(mut self, child: impl IntoElement) -> Self
Adds one arbitrary renderable child to this part. |
.style_with_state | pub fn style_with_state(mut self, style: impl Fn(NavigationMenuTriggerStyleState, Div) -> Div + 'static,) -> Self
Styles the part from its current behavioral state while preserving separation between behavior and visual design. |
.wired | pub fn wired(mut self, value: T, focus_handle: FocusHandle, entry_index: usize, order: usize,) -> Self
Internal wiring seam: the enclosing item hands the trigger its value, focus handle, roving entry index, and order. NavigationMenuTrigger also supports the GPUI traits implemented in its source, such as standard styling or child composition. |
#NavigationMenuPortal
Hosts overlay content outside the normal child layout.
use base_gpui::navigation_menu::NavigationMenuPortal;
NavigationMenuPortal::new()
.keep_mounted(true)
.style_with_state(|/* callback arguments */| { /* handle change */ });
#Builders
| Builder | Signature & description |
|---|---|
.new | pub fn new() -> SelfCreates a NavigationMenuPortal with its default configuration. |
.child | pub fn child(mut self, child: impl Into<NavigationMenuPortalChild<T>>) -> Self
Adds one typed child to this part. |
.child_any | pub fn child_any(mut self, child: impl IntoElement) -> Self
Adds one arbitrary renderable child to this part. |
.keep_mounted | pub fn keep_mounted(mut self, keep_mounted: bool) -> Self
Keeps the part mounted when inactive or closed so child state can be preserved. |
.style_with_state | pub fn style_with_state(mut self, style: impl Fn(NavigationMenuPortalStyleState, Div) -> Div + 'static,) -> Self
Styles the part from its current behavioral state while preserving separation between behavior and visual design. NavigationMenuPortal also supports the GPUI traits implemented in its source, such as standard styling or child composition. |
#NavigationMenuPositioner
Measures the anchor and positions floating content.
use base_gpui::navigation_menu::NavigationMenuPositioner;
NavigationMenuPositioner::new()
.side("example-id")
.align(/* align: NavigationMenuAlign */)
.side_offset("example-id")
.align_offset(/* align_offset: Pixels */)
.collision_padding(/* collision_padding: Pixels */)
.arrow_padding(/* arrow_padding: Pixels */)
.keep_mounted(true)
.style_with_state(|/* callback arguments */| { /* handle change */ });
#Builders
| Builder | Signature & description |
|---|---|
.new | pub fn new() -> SelfCreates a NavigationMenuPositioner with its default configuration. |
.child | pub fn child(mut self, child: impl Into<NavigationMenuPositionerChild<T>>) -> Self
Adds one typed child to this part. |
.child_any | pub fn child_any(mut self, child: impl IntoElement) -> Self
Adds one arbitrary renderable child to this part. |
.side | pub fn side(mut self, side: NavigationMenuSide) -> Self
Sets the preferred side of the anchor on which floating content appears. |
.align | pub fn align(mut self, align: NavigationMenuAlign) -> Self
Sets floating content alignment along the selected side. |
.side_offset | pub fn side_offset(mut self, side_offset: Pixels) -> Self
Sets the distance between floating content and its anchor. |
.align_offset | pub fn align_offset(mut self, align_offset: Pixels) -> Self
Offsets floating content along its alignment axis. |
.collision_padding | pub fn collision_padding(mut self, collision_padding: Pixels) -> Self
Sets the minimum space retained between floating content and viewport edges. |
.arrow_padding | pub fn arrow_padding(mut self, arrow_padding: Pixels) -> Self
Sets the arrow padding configuration for this part. |
.keep_mounted | pub fn keep_mounted(mut self, keep_mounted: bool) -> Self
Keeps the part mounted when inactive or closed so child state can be preserved. |
.style_with_state | pub fn style_with_state(mut self, style: impl Fn(NavigationMenuPositionerStyleState, Div) -> Div + 'static,) -> Self
Styles the part from its current behavioral state while preserving separation between behavior and visual design. NavigationMenuPositioner also supports the GPUI traits implemented in its source, such as standard styling or child composition. |
#NavigationMenuPopup
Contains the floating interactive content.
use base_gpui::navigation_menu::NavigationMenuPopup;
NavigationMenuPopup::new()
.side("example-id")
.align(/* align: NavigationMenuAlign */)
.aria_label("aria label")
.keep_mounted(true)
.style_with_state(|/* callback arguments */| { /* handle change */ });
#Builders
| Builder | Signature & description |
|---|---|
.new | pub fn new() -> SelfCreates a NavigationMenuPopup with its default configuration. |
.child | pub fn child(mut self, child: impl Into<NavigationMenuPopupChild<T>>) -> Self
Adds one typed child to this part. |
.child_any | pub fn child_any(mut self, child: impl IntoElement) -> Self
Adds one arbitrary renderable child to this part. |
.side | pub fn side(mut self, side: NavigationMenuSide) -> Self
Sets the preferred side of the anchor on which floating content appears. |
.align | pub fn align(mut self, align: NavigationMenuAlign) -> Self
Sets floating content alignment along the selected side. |
.aria_label | pub fn aria_label(mut self, aria_label: impl Into<SharedString>) -> Self
Accessible label for the popup group; use the same text as the root's |
.keep_mounted | pub fn keep_mounted(mut self, keep_mounted: bool) -> Self
Keeps the part mounted when inactive or closed so child state can be preserved. |
.style_with_state | pub fn style_with_state(mut self, style: impl Fn(NavigationMenuPopupStyleState, Div) -> Div + 'static,) -> Self
Styles the part from its current behavioral state while preserving separation between behavior and visual design. NavigationMenuPopup also supports the GPUI traits implemented in its source, such as standard styling or child composition. |
#NavigationMenuArrow
Optional arrow that visually points toward the overlay anchor.
use base_gpui::navigation_menu::NavigationMenuArrow;
NavigationMenuArrow::new()
.side("example-id")
.align(/* align: NavigationMenuAlign */)
.style_with_state(|/* callback arguments */| { /* handle change */ });
#Builders
| Builder | Signature & description |
|---|---|
.new | pub fn new() -> SelfCreates a NavigationMenuArrow with its default configuration. |
.side | pub fn side(mut self, side: NavigationMenuSide) -> Self
Sets the preferred side of the anchor on which floating content appears. |
.align | pub fn align(mut self, align: NavigationMenuAlign) -> Self
Sets floating content alignment along the selected side. |
.style_with_state | pub fn style_with_state(mut self, style: impl Fn(NavigationMenuArrowStyleState, Div) -> Div + 'static,) -> Self
Styles the part from its current behavioral state while preserving separation between behavior and visual design. NavigationMenuArrow also supports the GPUI traits implemented in its source, such as standard styling or child composition. |
#NavigationMenuBackdrop
Covers content behind a modal overlay and handles outside interaction.
use base_gpui::navigation_menu::NavigationMenuBackdrop;
NavigationMenuBackdrop::new()
.keep_mounted(true)
.style_with_state(|/* callback arguments */| { /* handle change */ });
#Builders
| Builder | Signature & description |
|---|---|
.new | pub fn new() -> SelfCreates a NavigationMenuBackdrop with its default configuration. |
.keep_mounted | pub fn keep_mounted(mut self, keep_mounted: bool) -> Self
Keeps the part mounted when inactive or closed so child state can be preserved. |
.style_with_state | pub fn style_with_state(mut self, style: impl Fn(NavigationMenuBackdropStyleState, Div) -> Div + 'static,) -> Self
Styles the part from its current behavioral state while preserving separation between behavior and visual design. NavigationMenuBackdrop also supports the GPUI traits implemented in its source, such as standard styling or child composition. |
#NavigationMenuContent
Contains the component's user-provided content.
use base_gpui::navigation_menu::NavigationMenuContent;
NavigationMenuContent::new()
.keep_mounted(true)
.style_with_state(|/* callback arguments */| { /* handle change */ })
.wired(/* value: T */)
.content_value();
#Builders
| Builder | Signature & description |
|---|---|
.new | pub fn new() -> SelfCreates a NavigationMenuContent with its default configuration. |
.keep_mounted | pub fn keep_mounted(mut self, keep_mounted: bool) -> Self
Keeps the part mounted when inactive or closed so child state can be preserved. |
.style_with_state | pub fn style_with_state(mut self, style: impl Fn(NavigationMenuContentStyleState, Div) -> Div + 'static,) -> Self
Styles the part from its current behavioral state while preserving separation between behavior and visual design. |
.wired | pub fn wired(mut self, value: T) -> Self
Internal wiring seam: the enclosing item hands the content its value. |
.content_value | pub fn content_value(&self) -> Option<&T>Sets the content value configuration for this part. NavigationMenuContent also supports the GPUI traits implemented in its source, such as standard styling or child composition. |
#NavigationMenuIcon
Optional visual icon for the component.
use base_gpui::navigation_menu::NavigationMenuIcon;
NavigationMenuIcon::new()
.with_value(/* value: T */)
.style_with_state(|/* callback arguments */| { /* handle change */ });
#Builders
| Builder | Signature & description |
|---|---|
.new | pub fn new() -> SelfCreates a NavigationMenuIcon with its default configuration. |
.with_value | pub fn with_value(mut self, value: T) -> Self
Internal wiring seam: the enclosing trigger hands the icon its item value. |
.style_with_state | pub fn style_with_state(mut self, style: impl Fn(NavigationMenuIconStyleState, Div) -> Div + 'static,) -> Self
Styles the part from its current behavioral state while preserving separation between behavior and visual design. NavigationMenuIcon also supports the GPUI traits implemented in its source, such as standard styling or child composition. |
#NavigationMenuItem
Represents one interactive item in the component's collection.
use base_gpui::navigation_menu::NavigationMenuItem;
NavigationMenuItem::new()
.value(/* value: T */)
.style_with_state(|/* callback arguments */| { /* handle change */ });
#Builders
| Builder | Signature & description |
|---|---|
.new | pub fn new() -> SelfCreates a NavigationMenuItem with its default configuration. |
.value | pub fn value(mut self, value: T) -> Self
Required: the item's value. Items without a value are not registered. |
.child | pub fn child(mut self, child: impl Into<NavigationMenuItemChild<T>>) -> Self
Adds one typed child to this part. |
.child_any | pub fn child_any(mut self, child: impl IntoElement) -> Self
Adds one arbitrary renderable child to this part. |
.style_with_state | pub fn style_with_state(mut self, style: impl Fn(NavigationMenuItemStyleState, Div) -> Div + 'static,) -> Self
Styles the part from its current behavioral state while preserving separation between behavior and visual design. NavigationMenuItem also supports the GPUI traits implemented in its source, such as standard styling or child composition. |
#NavigationMenuLink
Public renderable part of the Navigation Menu Link component.
use base_gpui::navigation_menu::NavigationMenuLink;
NavigationMenuLink::new()
.active(true)
.close_on_click(true)
.aria_label("aria label")
.on_activate(|/* callback arguments */| { /* handle change */ })
.style_with_state(|/* callback arguments */| { /* handle change */ });
#Builders
| Builder | Signature & description |
|---|---|
.new | pub fn new() -> SelfCreates a NavigationMenuLink with its default configuration. |
.active | pub fn active(mut self, active: bool) -> Self
Sets the active configuration for this part. |
.close_on_click | pub fn close_on_click(mut self, close_on_click: bool) -> Self
Controls whether close on click behavior is enabled. |
.aria_label | pub fn aria_label(mut self, aria_label: impl Into<SharedString>) -> Self
Accessible name for the link; pass one when the visible caption is not plain accessible text (no id-reference labelling exists). Render the visible caption with |
.on_activate | pub fn on_activate(mut self, on_activate: impl Fn(&mut Window, &mut App) + 'static) -> Self
Registers a callback invoked when activate occurs. |
.style_with_state | pub fn style_with_state(mut self, style: impl Fn(NavigationMenuLinkStyleState, Div) -> Div + 'static,) -> Self
Styles the part from its current behavioral state while preserving separation between behavior and visual design. NavigationMenuLink also supports the GPUI traits implemented in its source, such as standard styling or child composition. |
#NavigationMenuList
Contains and coordinates the component's collection items.
use base_gpui::navigation_menu::NavigationMenuList;
NavigationMenuList::new()
.style_with_state(|/* callback arguments */| { /* handle change */ });
#Builders
| Builder | Signature & description |
|---|---|
.new | pub fn new() -> SelfCreates a NavigationMenuList with its default configuration. |
.child | pub fn child(mut self, child: impl Into<NavigationMenuListChild<T>>) -> Self
Adds one typed child to this part. |
.child_any | pub fn child_any(mut self, child: impl IntoElement) -> Self
Adds one arbitrary renderable child to this part. |
.style_with_state | pub fn style_with_state(mut self, style: impl Fn(NavigationMenuListStyleState, Div) -> Div + 'static,) -> Self
Styles the part from its current behavioral state while preserving separation between behavior and visual design. NavigationMenuList also supports the GPUI traits implemented in its source, such as standard styling or child composition. |
#NavigationMenuViewport
Defines the viewport used to lay out or constrain overlay content.
use base_gpui::navigation_menu::NavigationMenuViewport;
NavigationMenuViewport::new()
.with_contents(/* contents: Vec<NavigationMenuContent<T>> */)
.style_with_state(|/* callback arguments */| { /* handle change */ });
#Builders
| Builder | Signature & description |
|---|---|
.new | pub fn new() -> SelfCreates a NavigationMenuViewport with its default configuration. |
.with_contents | pub fn with_contents(mut self, contents: Vec<NavigationMenuContent<T>>) -> Self
Internal wiring seam: receives the contents collected from items. |
.style_with_state | pub fn style_with_state(mut self, style: impl Fn(NavigationMenuViewportStyleState, Div) -> Div + 'static,) -> Self
Styles the part from its current behavioral state while preserving separation between behavior and visual design. NavigationMenuViewport also supports the GPUI traits implemented in its source, such as standard styling or child composition. |
#Accessibility
Keyboard interaction and accessibility semantics are implemented by the component, independently of visual styling. Known limitations caused by missing GPUI accessibility primitives are documented in the module source and are not silently approximated.
#Stability
Base GPUI is pre-1.0. Builder names and state types may evolve as GPUI and this port mature.