Theme
Version
GitHub PyPI Discord
On this page

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
Native navigation links
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

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

Controlled NavigationMenu
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

NavigationMenu orientations
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

NavigationMenu 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

NavigationMenu 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

NavigationMenu keyboard behavior
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

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(...).

InputTypeDefaultEffect
labelstrrequiredNames the native navigation landmark.
idstr | NonegeneratedSets root identity and generated trigger/panel relationship prefixes.
valuestr | NoneNoneSelects the server-open Item and uncontrolled fallback.
orientation"horizontal" | "vertical" (CNavigationMenuOrientation)"horizontal"Sets visual layout and optional arrow-key axis.
disabledboolFalsePrevents disclosure opening and forces an open panel closed.
delayint200Sets fine-pointer open delay from 0 through 60000 milliseconds.
close_delayint300Sets fine-pointer root-leave close delay from 0 through 60000 milliseconds.
loopboolFalseAllows 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)NoneAdds root classes.
styleCStyleValue (CStyleValue)NoneAdds root inline styles.
attrsMapping[str, object] | NoneNoneAdds 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 />.

InputTypeOmitted behaviorEffect
valuestring | nullReleases control and preserves committed state.Controls the open Item while supplied.
disabledbooleanUses the server input.Reactively disables disclosure behavior.
delayintegerUses the server input.Controls future pointer-open delay.
closeDelayintegerUses the server input.Controls future pointer-close delay.
loopbooleanUses the server input.Controls arrow-key wrapping.
orientationCNavigationMenuOrientationUses the server input.Changes layout and keyboard axis.
variantCNavigationMenuVariantUses the server input.Changes root treatment.
sizeCNavigationMenuSizeUses the server input.Changes tree geometry.
onValueChangefunctionDoes not notify a component callback.Receives open-value requests and forced safety closes.

Server inputs are passed in a template through <c-CNavigationMenuLink ... /> or in Python through CNavigationMenuLink(...).

InputTypeDefaultEffect
hrefstrrequiredSets the native link destination without URL rewriting.
currentboolFalseEmits aria-current page.
targetstr | NoneNoneSets native target.
relstr | NoneNoneSets native rel.
downloadstr | NoneNoneSets native download.
class_CClassValue (CClassValue)NoneAdds list-item classes.
styleCStyleValue (CStyleValue)NoneAdds list-item styles.
attrsMapping[str, object] | NoneNoneAdds allowed list-item attributes.
link_attrsMapping[str, object] | NoneNoneAdds allowed native link attributes.

CNavigationMenuItem server inputs

Server inputs are passed in a template through <c-CNavigationMenuItem ... /> or in Python through CNavigationMenuItem(...).

InputTypeDefaultEffect
valuestrrequiredSets unique Item identity and callback value.
disabledboolFalseDisables the disclosure Button.
class_CClassValue (CClassValue)NoneAdds list-item classes.
styleCStyleValue (CStyleValue)NoneAdds list-item styles.
attrsMapping[str, object] | NoneNoneAdds allowed list-item attributes.
trigger_attrsMapping[str, object] | NoneNoneAdds allowed native Button attributes.
panel_attrsMapping[str, object] | NoneNoneAdds 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

SlotRequiredDataFallback
defaultyes{} (CNavigationMenuDefaultSlotData)none
SlotRequiredDataFallback
defaultyes{} (CNavigationMenuLinkDefaultSlotData)none

CNavigationMenuItem slots

SlotRequiredDataFallback
labelyes{} (CNavigationMenuItemLabelSlotData)none
defaultyes{} (CNavigationMenuItemDefaultSlotData)none

Events

Component events are callback inputs supplied through $c-props. Native browser events remain available through Alpine @... attributes.

CNavigationMenu events

EventSignatureTrigger and timingDetailControlled 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.

VariableTypePurposeDefault
--cui-navigation-menu-backgroundcolorRoot background.transparent
--cui-navigation-menu-foregroundcolorTree foreground.CanvasText
--cui-navigation-menu-border-colorcolorSurface boundaries.Scheme-aware neutral.
--cui-navigation-menu-trigger-backgroundcolorResting top-level control background.transparent
--cui-navigation-menu-trigger-hover-backgroundcolorHovered control background.Scheme-aware neutral.
--cui-navigation-menu-trigger-open-backgroundcolorOpen control background.Scheme-aware neutral.
--cui-navigation-menu-focus-colorcolorFocus ring.Highlight
--cui-navigation-menu-radiuslengthRoot and panel radius.0.75rem
--cui-navigation-menu-gaplengthTop-level gap.0.25rem
--cui-navigation-menu-paddinglengthRoot padding.Size-derived.
--cui-navigation-menu-panel-backgroundcolorPanel surface.Canvas
--cui-navigation-menu-panel-inline-sizelengthPreferred panel width.24rem
--cui-navigation-menu-panel-max-inline-sizelengthViewport-safe maximum panel width.calc(100vw - 2rem)
--cui-navigation-menu-panel-paddinglengthPanel padding.1rem
--cui-navigation-menu-panel-shadowshadowPanel elevation.Scheme-aware shadow.
--cui-navigation-menu-offsetlengthPanel offset.0.45rem
--cui-navigation-menu-durationtimeIndicator transition duration.150ms
--cui-navigation-menu-easingeasingIndicator 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

AttributeElementTypeMeaning
aria-labelRoot navstringNames the navigation landmark.
data-orientationRoot navCNavigationMenuOrientationReflects layout and arrow-key axis.
data-disabledRoot and disabled Item/triggerpresent | absentReflects effective component disabledness.
data-loopRoot navpresent | absentReflects arrow wrapping.
data-variantRoot navCNavigationMenuVariantReflects treatment.
data-sizeRoot navCNavigationMenuSizeReflects geometry.
data-valueRoot Item trigger and panelstringReflects open or owned Item identity according to destination.
data-openOpen Item trigger and panelpresent | absentReflects open state.
aria-currentCurrent Link"page"Identifies the current destination.
aria-controlsItem triggerIDREFPoints to the adjacent panel.
aria-expandedItem trigger"true" | "false"Reflects panel visibility.
disabledItem triggerpresent | absentUses native Button disabledness.
hiddenClosed panelpresent | absentRemoves closed content from rendering and accessibility.
inertClosed panelpresent | absentPrevents programmatic closed-panel interaction.

Selectors

Selectors for the DOM nodes in the components that you can use for CSS, inspection, and testing.

CNavigationMenu selectors

SelectorElementPurpose
[data-citry-ui-part="navigation-menu"]navRoot style and attrs destination.
[data-citry-ui-part="list"]ulDirect child collection.
[data-citry-ui-part="link-item"]Link liLink list item.
[data-citry-ui-part="link"]Native aNavigation destination.
[data-citry-ui-part="item"]Disclosure liItem state boundary.
[data-citry-ui-part="trigger"]Native ButtonDisclosure control.
[data-citry-ui-part="indicator"]Decorative spanOpen-state chevron.
[data-citry-ui-part="panel"]Neutral divRich navigation content.

Interfaces

Aliases and data shapes referenced above.

Input type aliases

InterfaceDefinition
CClassValuestr | Mapping[str, bool] | Sequence[CClassValue]
CStyleValuestr | Mapping[str, str | int | float | bool | None] | Sequence[CStyleValue]
CNavigationMenuOrientationLiteral["horizontal", "vertical"]
CNavigationMenuVariantLiteral["plain", "surface"]
CNavigationMenuSizeLiteral["sm", "md", "lg"]

CNavigationMenuDefaultSlotData

Empty dataclass: {}.

CNavigationMenuLinkDefaultSlotData

Empty dataclass: {}.

CNavigationMenuItemLabelSlotData

Empty dataclass: {}.

CNavigationMenuItemDefaultSlotData

Empty dataclass: {}.

CNavigationMenuValueChangeDetail

FieldTypeDefaultMeaning
valuestr | None-Requested open value.
previousValuestr | None-Previously effective value.
reasonstring-Request source.
controlledboolean-Whether a supplied client value owns state.
forcedboolean-Whether safety close overrides control.
sourceEventTarget | null-Browser source.

Translation keys

-