NavigationMenu
Use CNavigationMenu for persistent site navigation whose top-level entries are native links or Buttons that disclose richer link collections. It keeps ordinary nav, list, link, and Tab behaviorβapplication commands belong in CMenu.
NavigationMenu at a glance
Show code
# ruff: noqa: E501
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class NavigationMenuAtAGlance(Component):
template = """
<c-CNavigationMenu label="Main navigation" variant="surface">
<c-CNavigationMenuLink href="#overview" c-current="True">Overview</c-CNavigationMenuLink>
<c-CNavigationMenuItem value="products">
<c-fill name="label">Products</c-fill>
<c-fill name="default"><c-CStack gap="sm"><strong>Explore products</strong><a href="#analytics">Analytics</a><a href="#automations">Automations</a></c-CStack></c-fill>
</c-CNavigationMenuItem>
<c-CNavigationMenuLink href="#pricing">Pricing</c-CNavigationMenuLink>
</c-CNavigationMenu>
"""
preview = NavigationMenuAtAGlance()
preview # noqa: B018
Link-only navigation
Show code
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class NavigationLinks(Component):
template = """
<c-CNavigationMenu label="Documentation">
<c-CNavigationMenuLink href="#guide" c-current="True">Guide</c-CNavigationMenuLink>
<c-CNavigationMenuLink href="#reference">Reference</c-CNavigationMenuLink>
<c-CNavigationMenuLink href="#examples">Examples</c-CNavigationMenuLink>
</c-CNavigationMenu>
"""
preview = NavigationLinks()
preview # noqa: B018
Rich navigation panels
Show code
# ruff: noqa: E501
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class RichNavigationPanels(Component):
template = """
<c-CNavigationMenu label="Product navigation" value="platform">
<c-CNavigationMenuLink href="#home">Home</c-CNavigationMenuLink>
<c-CNavigationMenuItem value="platform">
<c-fill name="label">Platform</c-fill>
<c-fill name="default"><c-CGrid cols="2" gap="sm"><c-CCard variant="subtle"><c-fill name="header"><strong>Observe</strong></c-fill><c-fill name="default">Capture field signals.</c-fill></c-CCard><c-CCard variant="subtle"><c-fill name="header"><strong>Coordinate</strong></c-fill><c-fill name="default">Keep teams aligned.</c-fill></c-CCard></c-CGrid></c-fill>
</c-CNavigationMenuItem>
<c-CNavigationMenuLink href="#company">Company</c-CNavigationMenuLink>
</c-CNavigationMenu>
"""
preview = RichNavigationPanels()
preview # noqa: B018
Control the open panel
Show code
# ruff: noqa: E501
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class ControlledNavigation(Component):
template = """
<section x-data="{open:null}"><p>Open: <strong x-text="open ?? 'none'"></strong></p>
<c-CNavigationMenu label="Controlled navigation" $c-props="{value:open,onValueChange:(next)=>open=next}">
<c-CNavigationMenuLink href="#home">Home</c-CNavigationMenuLink>
<c-CNavigationMenuItem value="learn"><c-fill name="label">Learn</c-fill><c-fill name="default"><a href="#tutorials">Tutorials</a></c-fill></c-CNavigationMenuItem>
</c-CNavigationMenu>
</section>
"""
preview = ControlledNavigation()
preview # noqa: B018
Choose orientation
Show code
# ruff: noqa: E501
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class NavigationOrientation(Component):
template = """
<c-CNavigationMenu label="Account navigation" orientation="vertical" variant="surface">
<c-CNavigationMenuLink href="#profile" c-current="True">Profile</c-CNavigationMenuLink>
<c-CNavigationMenuItem value="teams"><c-fill name="label">Teams</c-fill><c-fill name="default"><a href="#research">Research</a><br><a href="#operations">Operations</a></c-fill></c-CNavigationMenuItem>
<c-CNavigationMenuLink href="#billing">Billing</c-CNavigationMenuLink>
</c-CNavigationMenu>
"""
preview = NavigationOrientation()
preview # noqa: B018
Disabled states
Show code
# ruff: noqa: E501
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class NavigationStates(Component):
template = """
<c-CNavigationMenu label="Navigation states">
<c-CNavigationMenuLink href="#home" c-current="True">Current page</c-CNavigationMenuLink>
<c-CNavigationMenuItem value="available"><c-fill name="label">Available</c-fill><c-fill name="default">Ready to explore.</c-fill></c-CNavigationMenuItem>
<c-CNavigationMenuItem value="locked" disabled><c-fill name="label">Unavailable</c-fill><c-fill name="default">Hidden panel.</c-fill></c-CNavigationMenuItem>
</c-CNavigationMenu>
"""
preview = NavigationStates()
preview # noqa: B018
Variants and sizes
Show code
# ruff: noqa: E501
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class NavigationVariants(Component):
template = """
<c-CStack gap="lg"><c-CNavigationMenu label="Small plain" size="sm"><c-CNavigationMenuLink href="#one">Small</c-CNavigationMenuLink><c-CNavigationMenuItem value="more"><c-fill name="label">More</c-fill><c-fill name="default">Small panel</c-fill></c-CNavigationMenuItem></c-CNavigationMenu><c-CNavigationMenu label="Large surface" variant="surface" size="lg"><c-CNavigationMenuLink href="#two">Large</c-CNavigationMenuLink><c-CNavigationMenuItem value="details"><c-fill name="label">Details</c-fill><c-fill name="default">Large panel</c-fill></c-CNavigationMenuItem></c-CNavigationMenu></c-CStack>
"""
preview = NavigationVariants()
preview # noqa: B018
Keyboard navigation
Show code
# ruff: noqa: E501
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class NavigationKeyboard(Component):
template = """
<c-CStack gap="sm"><p>Tab normally. Use Arrow keys between top-level controls, Down to enter an open panel, and Escape to close it.</p><c-CNavigationMenu label="Keyboard example" loop><c-CNavigationMenuLink href="#start">Start</c-CNavigationMenuLink><c-CNavigationMenuItem value="topics"><c-fill name="label">Topics</c-fill><c-fill name="default"><a href="#accessibility">Accessibility</a></c-fill></c-CNavigationMenuItem><c-CNavigationMenuLink href="#finish">Finish</c-CNavigationMenuLink></c-CNavigationMenu></c-CStack>
"""
preview = NavigationKeyboard()
preview # noqa: B018
Customize NavigationMenu
Show code
# ruff: noqa: E501
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class CustomNavigation(Component):
template = """
<c-CNavigationMenu label="Aurora navigation" class_="aurora-nav" variant="surface"><c-CNavigationMenuLink href="#mission">Mission</c-CNavigationMenuLink><c-CNavigationMenuItem value="field-notes"><c-fill name="label">Field notes</c-fill><c-fill name="default"><strong>Fresh observations</strong><p>Follow the latest work from the field.</p></c-fill></c-CNavigationMenuItem></c-CNavigationMenu>
"""
css = """
.aurora-nav { --cui-navigation-menu-trigger-open-background:#dbeafe; --cui-navigation-menu-radius:1rem; --cui-navigation-menu-panel-inline-size:20rem; }
"""
preview = CustomNavigation()
preview # noqa: B018
Accessibility and interaction
Give every root a concise label. Links remain native and all top-level links and disclosure Buttons remain in ordinary Tab order. Arrow keys provide an additional convenience between top-level controls; Escape closes an open panel and returns focus to its Button. Panels can contain ordinary links, Buttons, and forms, but nested NavigationMenu disclosures are intentionally deferred.
API reference
Inputs
CNavigationMenu server inputs
Server inputs are passed in a template through <c-CNavigationMenu ... /> or in Python through CNavigationMenu(...).
| Input | Type | Default | Effect |
|---|---|---|---|
label | str | required | Names the native navigation landmark. |
id | str | None | generated | Sets root identity and generated trigger/panel relationship prefixes. |
value | str | None | None | Selects the server-open Item and uncontrolled fallback. |
orientation | "horizontal" | "vertical" (CNavigationMenuOrientation) | "horizontal" | Sets visual layout and optional arrow-key axis. |
disabled | bool | False | Prevents disclosure opening and forces an open panel closed. |
delay | int | 200 | Sets fine-pointer open delay from 0 through 60000 milliseconds. |
close_delay | int | 300 | Sets fine-pointer root-leave close delay from 0 through 60000 milliseconds. |
loop | bool | False | Allows optional top-level arrow navigation to wrap. |
variant | "plain" | "surface" (CNavigationMenuVariant) | "plain" | Selects root visual treatment. |
size | "sm" | "md" | "lg" (CNavigationMenuSize) | "md" | Selects geometry for the complete tree. |
class_ | CClassValue (CClassValue) | None | Adds root classes. |
style | CStyleValue (CStyleValue) | None | Adds root inline styles. |
attrs | Mapping[str, object] | None | None | Adds allowed native and data attributes to the nav root. |
CNavigationMenu client inputs
Client inputs are passed in the browser through the $c-props="{ ... }" attribute on <c-CNavigationMenu />.
| Input | Type | Omitted behavior | Effect |
|---|---|---|---|
value | string | null | Releases control and preserves committed state. | Controls the open Item while supplied. |
disabled | boolean | Uses the server input. | Reactively disables disclosure behavior. |
delay | integer | Uses the server input. | Controls future pointer-open delay. |
closeDelay | integer | Uses the server input. | Controls future pointer-close delay. |
loop | boolean | Uses the server input. | Controls arrow-key wrapping. |
orientation | CNavigationMenuOrientation | Uses the server input. | Changes layout and keyboard axis. |
variant | CNavigationMenuVariant | Uses the server input. | Changes root treatment. |
size | CNavigationMenuSize | Uses the server input. | Changes tree geometry. |
onValueChange | function | Does not notify a component callback. | Receives open-value requests and forced safety closes. |
CNavigationMenuLink server inputs
Server inputs are passed in a template through <c-CNavigationMenuLink ... /> or in Python through CNavigationMenuLink(...).
| Input | Type | Default | Effect |
|---|---|---|---|
href | str | required | Sets the native link destination without URL rewriting. |
current | bool | False | Emits aria-current page. |
target | str | None | None | Sets native target. |
rel | str | None | None | Sets native rel. |
download | str | None | None | Sets native download. |
class_ | CClassValue (CClassValue) | None | Adds list-item classes. |
style | CStyleValue (CStyleValue) | None | Adds list-item styles. |
attrs | Mapping[str, object] | None | None | Adds allowed list-item attributes. |
link_attrs | Mapping[str, object] | None | None | Adds allowed native link attributes. |
CNavigationMenuItem server inputs
Server inputs are passed in a template through <c-CNavigationMenuItem ... /> or in Python through CNavigationMenuItem(...).
| Input | Type | Default | Effect |
|---|---|---|---|
value | str | required | Sets unique Item identity and callback value. |
disabled | bool | False | Disables the disclosure Button. |
class_ | CClassValue (CClassValue) | None | Adds list-item classes. |
style | CStyleValue (CStyleValue) | None | Adds list-item styles. |
attrs | Mapping[str, object] | None | None | Adds allowed list-item attributes. |
trigger_attrs | Mapping[str, object] | None | None | Adds allowed native Button attributes. |
panel_attrs | Mapping[str, object] | None | None | Adds allowed panel attributes. |
Slots
Slots are passed as nested content or <c-fill> tags in a template, or through the slots={...} argument in Python.
CNavigationMenu slots
| Slot | Required | Data | Fallback |
|---|---|---|---|
default | yes | {} (CNavigationMenuDefaultSlotData) | none |
CNavigationMenuLink slots
| Slot | Required | Data | Fallback |
|---|---|---|---|
default | yes | {} (CNavigationMenuLinkDefaultSlotData) | none |
CNavigationMenuItem slots
| Slot | Required | Data | Fallback |
|---|---|---|---|
label | yes | {} (CNavigationMenuItemLabelSlotData) | none |
default | yes | {} (CNavigationMenuItemDefaultSlotData) | none |
Events
Component events are callback inputs supplied through $c-props. Native browser events remain available through Alpine @... attributes.
CNavigationMenu events
| Event | Signature | Trigger and timing | Detail | Controlled and cancellation behavior |
|---|---|---|---|---|
onValueChange | (value: string | null, detail: CNavigationMenuValueChangeDetail) => void (CNavigationMenuValueChangeDetail) | Trigger, hover, Escape, outside interaction, link activation, disabledness, or structure requests a different open value. | {value, previousValue, reason, controlled, forced, source} (CNavigationMenuValueChangeDetail) | Uncontrolled requests commit before notification; controlled requests wait for acceptance; safety closes are forced. |
Methods
-
CSS
CSS variables to theme the components. Set them on an ancestor or the component itself.
CNavigationMenu CSS variables
Apply these variables to CNavigationMenu or one of its ancestors.
| Variable | Type | Purpose | Default |
|---|---|---|---|
--cui-navigation-menu-background | color | Root background. | transparent |
--cui-navigation-menu-foreground | color | Tree foreground. | CanvasText |
--cui-navigation-menu-border-color | color | Surface boundaries. | Scheme-aware neutral. |
--cui-navigation-menu-trigger-background | color | Resting top-level control background. | transparent |
--cui-navigation-menu-trigger-hover-background | color | Hovered control background. | Scheme-aware neutral. |
--cui-navigation-menu-trigger-open-background | color | Open control background. | Scheme-aware neutral. |
--cui-navigation-menu-focus-color | color | Focus ring. | Highlight |
--cui-navigation-menu-radius | length | Root and panel radius. | 0.75rem |
--cui-navigation-menu-gap | length | Top-level gap. | 0.25rem |
--cui-navigation-menu-padding | length | Root padding. | Size-derived. |
--cui-navigation-menu-panel-background | color | Panel surface. | Canvas |
--cui-navigation-menu-panel-inline-size | length | Preferred panel width. | 24rem |
--cui-navigation-menu-panel-max-inline-size | length | Viewport-safe maximum panel width. | calc(100vw - 2rem) |
--cui-navigation-menu-panel-padding | length | Panel padding. | 1rem |
--cui-navigation-menu-panel-shadow | shadow | Panel elevation. | Scheme-aware shadow. |
--cui-navigation-menu-offset | length | Panel offset. | 0.45rem |
--cui-navigation-menu-duration | time | Indicator transition duration. | 150ms |
--cui-navigation-menu-easing | easing | Indicator transition easing. | ease-out |
Attributes
HTML attributes defined on the components that you can refer to for CSS, inspection, and testing. Read-only.
CNavigationMenu attributes
| Attribute | Element | Type | Meaning |
|---|---|---|---|
aria-label | Root nav | string | Names the navigation landmark. |
data-orientation | Root nav | CNavigationMenuOrientation | Reflects layout and arrow-key axis. |
data-disabled | Root and disabled Item/trigger | present | absent | Reflects effective component disabledness. |
data-loop | Root nav | present | absent | Reflects arrow wrapping. |
data-variant | Root nav | CNavigationMenuVariant | Reflects treatment. |
data-size | Root nav | CNavigationMenuSize | Reflects geometry. |
data-value | Root Item trigger and panel | string | Reflects open or owned Item identity according to destination. |
data-open | Open Item trigger and panel | present | absent | Reflects open state. |
aria-current | Current Link | "page" | Identifies the current destination. |
aria-controls | Item trigger | IDREF | Points to the adjacent panel. |
aria-expanded | Item trigger | "true" | "false" | Reflects panel visibility. |
disabled | Item trigger | present | absent | Uses native Button disabledness. |
hidden | Closed panel | present | absent | Removes closed content from rendering and accessibility. |
inert | Closed panel | present | absent | Prevents programmatic closed-panel interaction. |
Selectors
Selectors for the DOM nodes in the components that you can use for CSS, inspection, and testing.
CNavigationMenu selectors
| Selector | Element | Purpose |
|---|---|---|
[data-citry-ui-part="navigation-menu"] | nav | Root style and attrs destination. |
[data-citry-ui-part="list"] | ul | Direct child collection. |
[data-citry-ui-part="link-item"] | Link li | Link list item. |
[data-citry-ui-part="link"] | Native a | Navigation destination. |
[data-citry-ui-part="item"] | Disclosure li | Item state boundary. |
[data-citry-ui-part="trigger"] | Native Button | Disclosure control. |
[data-citry-ui-part="indicator"] | Decorative span | Open-state chevron. |
[data-citry-ui-part="panel"] | Neutral div | Rich navigation content. |
Interfaces
Aliases and data shapes referenced above.
Input type aliases
| Interface | Definition |
|---|---|
CClassValue | str | Mapping[str, bool] | Sequence[CClassValue] |
CStyleValue | str | Mapping[str, str | int | float | bool | None] | Sequence[CStyleValue] |
CNavigationMenuOrientation | Literal["horizontal", "vertical"] |
CNavigationMenuVariant | Literal["plain", "surface"] |
CNavigationMenuSize | Literal["sm", "md", "lg"] |
CNavigationMenuDefaultSlotData
Empty dataclass: {}.
CNavigationMenuLinkDefaultSlotData
Empty dataclass: {}.
CNavigationMenuItemLabelSlotData
Empty dataclass: {}.
CNavigationMenuItemDefaultSlotData
Empty dataclass: {}.
CNavigationMenuValueChangeDetail
| Field | Type | Default | Meaning |
|---|---|---|---|
value | str | None | - | Requested open value. |
previousValue | str | None | - | Previously effective value. |
reason | string | - | Request source. |
controlled | boolean | - | Whether a supplied client value owns state. |
forced | boolean | - | Whether safety close overrides control. |
source | EventTarget | null | - | Browser source. |
Translation keys
-