Application navigation

A labelled application destination tree with explicit body anatomy, current state, icons, badges, sections, and flexible spacing.

Source: app/components/nitro_kit/app_navigation.rb
API: NitroKit::AppNavigation.new(label:, id:) { |navigation| navigation.body { ... } }

Rubytest/dummy/app/components/gallery/components/app_navigation_page.rb

render NitroKit::AppNavigation.new(
  id: "gallery-app-navigation-complete",
  label: "Workspace",
  data: { gallery_navigation_preview: "complete" }
) do |navigation|
  navigation.footer do
    render_account_menu(id: "gallery-app-navigation-account")
  end
  navigation.body do
    navigation.section(label: "Workspace") do
      navigation.item("Overview", href: "#overview", icon: :house, current: true)
      navigation.item("Projects", href: "#projects", icon: :folder, badge: 12)
      navigation.item("People", href: "#people", icon: :users)
    end
    navigation.divider
    navigation.section(label: "Manage") do
      navigation.item("Automations", href: "#automations", icon: :zap, badge: "New")
      navigation.item("Settings", href: "#settings", icon: :settings)
    end
    navigation.spacer
    navigation.item("Help and support", href: "#help", icon: :circle_help)
  end
  navigation.header do
    render NitroKit::Badge.new("Production", variant: :outline, size: :sm)
  end
end

Rubytest/dummy/app/components/gallery/components/app_navigation_page.rb

destinations = [ [ "Home", "#minimal-home", :house ] ]

render NitroKit::AppNavigation.new(
  id: "gallery-app-navigation-minimal",
  label: "Minimal",
  data: { gallery_navigation_preview: "minimal" }
) do |navigation|
  navigation.body do
    destinations.each do |text, href, icon|
      navigation.item(text, href:, icon:, current: true)
    end
  end
end

Two labelled groups

Rubytest/dummy/app/components/gallery/components/app_navigation_page.rb

render NitroKit::AppNavigation.new(
  id: "gallery-app-navigation-groups",
  label: "Grouped destinations",
  data: { gallery_navigation_preview: "groups" }
) do |navigation|
  navigation.body do
    navigation.section(label: "Plan") do
      navigation.item("Roadmap", href: "#roadmap", icon: :map)
      navigation.item("Milestones", href: "#milestones", icon: :flag, current: true)
    end
    navigation.section(label: "Observe") do
      navigation.item("Activity", href: "#activity", icon: :activity)
      navigation.item("Reports", href: "#reports", icon: :chart_no_axes_column)
    end
  end
end

Rubytest/dummy/app/components/gallery/components/app_navigation_page.rb

render NitroKit::AppNavigation.new(
  id: "gallery-app-navigation-collapsible",
  label: "Collapsible destinations",
  data: { gallery_navigation_preview: "collapsible" }
) do |navigation|
  navigation.body do
    navigation.section(label: "Plan", collapsible: true) do
      navigation.item("Roadmap", href: "#collapsible-roadmap", icon: :map)
      navigation.item("Milestones", href: "#collapsible-milestones", icon: :flag, current: true)
    end
    navigation.section(label: "Archive", collapsible: true, expanded: false) do
      navigation.item("Exports", href: "#collapsible-exports", icon: :archive)
      navigation.item("Retired projects", href: "#collapsible-retired", icon: :folder)
    end
  end
end

Rubytest/dummy/app/components/gallery/components/app_navigation_page.rb

render NitroKit::AppNavigation.new(
  id: "gallery-app-navigation-pressure",
  label: "International research workspace",
  data: { gallery_navigation_preview: "pressure" }
) do |navigation|
  navigation.body do
    navigation.section(label: "International Research and Production") do
      navigation.item(
        "Analytical engine reliability and production readiness",
        href: "#reliability",
        icon: :gauge,
        badge: 128,
        current: true
      )
      navigation.item(
        "Cross-regional incident response and operational handoffs",
        href: "#incidents",
        icon: :siren,
        badge: "Urgent"
      )
      navigation.item(
        "Quarterly capacity forecasts and allocation planning",
        href: "#capacity",
        icon: :calendar_range
      )
    end
    navigation.section(label: "Unaccompanied labels") do
      navigation.item(
        "Regional data residency and retention commitments",
        href: "#residency",
        badge: 64
      )
      navigation.item(
        "Deprecated provisioning workflows awaiting removal",
        href: "#deprecated"
      )
    end
    navigation.spacer
    navigation.divider
    navigation.item("Workspace settings", href: "#workspace-settings", icon: :settings)
  end
  navigation.footer do
    render NitroKit::ButtonGroup.new(label: "Workspace help") do |group|
      group.button("Docs", href: "#docs", size: :sm)
      group.button("Support", href: "#support", size: :sm)
    end
  end
end

Rubytest/dummy/app/components/gallery/components/app_navigation_page.rb

render NitroKit::AppNavigation.new(
  id: "gallery-app-navigation-item-attributes",
  label: "Item attributes"
) do |navigation|
  navigation.body do
    navigation.item(
      "Incidents",
      href: "#item-attributes-incidents",
      icon: :siren,
      badge: 3,
      badge_color: :destructive,
      current: true,
      data: { turbo_frame: "gallery-content" }
    )
    navigation.item(
      "Deployments",
      href: "#item-attributes-deployments",
      icon: :rocket,
      badge: "Live",
      badge_color: :success
    )
    navigation.item(
      "Status page",
      href: "https://status.example.com",
      icon: :external_link,
      html: { target: "_blank", rel: "noopener noreferrer" },
      aria: { describedby: "gallery-app-navigation-external-note" }
    )
  end
  navigation.footer do
    p(id: "gallery-app-navigation-external-note") { "External destinations open in a new tab." }
  end
end

Rubytest/dummy/app/components/gallery/components/app_navigation_page.rb

render NitroKit::AppNavigation.new(
  id: "gallery-app-navigation-hostile",
  label: Gallery::Hostile::LONG_LABEL,
  data: { gallery_navigation_preview: "hostile" }
) do |navigation|
  navigation.header { strong { Gallery::Hostile::LONG_NAME } }
  navigation.body do
    navigation.section(label: Gallery::Hostile::LONG_LABEL) do
      Gallery::Hostile::NAVIGATION_LABELS.each_with_index do |label, index|
        navigation.item(
          label,
          href: "#{Gallery::Hostile::LONG_URL}#destination-#{index}",
          icon: index.even? ? :folder : nil,
          badge: Gallery::Hostile::BADGE_LABELS[index],
          current: index == 1
        )
      end
    end
    navigation.section(label: Gallery::Hostile::LONG_WORD, collapsible: true) do
      Gallery::Hostile::TAB_LABELS.each_with_index do |label, index|
        navigation.item(label, href: "#{Gallery::Hostile::LONG_URL}#setting-#{index}")
      end
    end
    navigation.spacer
    navigation.divider
    navigation.item(
      Gallery::Hostile::LONG_WORD,
      href: Gallery::Hostile::LONG_URL,
      icon: :settings,
      badge: Gallery::Hostile::HUGE_FORMATTED
    )
  end
  navigation.footer do
    p { Gallery::Hostile::LONG_EMAIL }
  end
end

Component contract

Constructor options, rendered root, closed vocabularies, and compound boundary for this component, exactly as shipped.

docs/component_contracts.md · NitroKit::AppNavigation

Constructor-specific options: required label:
id: nil
Root and closed vocabulary: native nav[data-nk=app-navigation]
Compound contract: Requires one body and at least one item. The body is a ul; every entry is an li. Optional unique header and footer surround ordered section(label: nil, collapsible: false, expanded: true), divider, item(text, href:, icon: nil, icon_end: nil, badge: nil, badge_color: :neutral, current: false, html:, aria:, data:, desperately_need_a_class:), and at most one spacer. A section renders a span label plus a nested ul named through aria-label; it emits no heading. A collapsible section requires a label and renders native details and summary with an owned chevron, so open state lives on the open attribute without JavaScript; expanded: sets the initial state. Items render li > a[data-slot=app-navigation-item-link] and carry the item attribute bags. Icon and badge vocabularies are validated as the item is declared. At most one item is current.

Relevant patterns

Application conventions this component belongs to. Each summary is the leading section of its pattern document.

docs/patterns/application_foundation.md

Application foundation

Model User, Team, and Membership; roles belong to memberships, and tenant-owned records load through Current.team.
Use one AppShell for the authenticated product and one application-owned content gutter inside shell.main.
Put route titles and persistent actions in the shell Toolbar; keep destinations in AppNavigation.
Use links for settings destinations and one layout-level Toast::FlashMessages region for server feedback.

System rules for coding agents

Instructions for coding agents, repeated on every component page so one fetched page has enough context. Humans can usually skip this section.

test/dummy/app/components/gallery/agent_rules.rb

View agent instructions

Nitro Kit 2.0 is a gem-owned, Phlex-only UI system for Rails. Render components directly: render NitroKit::Button.new("Save", variant: :primary).
Compose Nitro components inside application-owned Phlex classes. Public initializers and declared slots are the component API; private methods are not.
Public options are explicit keywords, and enumerated options are closed vocabularies. Invalid names or values raise ArgumentError; this component's accepted options are in the contract above.
Pass native attributes through their typed boundary: html: for HTML, aria: for ARIA, and data: for application data. class and style are forbidden, including inside html:.
Nitro owns NitroKit::Component::RESERVED_DATA_ATTRIBUTES: data-nk, data-slot, data-variant, data-size, data-nk-escape, data-enhanced, data-state, data-disabled, data-required, data-orientation, data-presentation, data-placement, data-layout, data-side, data-field-type, data-dir, data-gap, data-align, data-justify, data-wrap, data-cols, data-mode, data-key. Do not pass them through data:. data-action, data-controller are additive and compose with Nitro behavior.
If an integration truly requires a class, use desperately_need_a_class:. It requires a non-blank String and marks the exception with data-nk-escape="class".
Every root emits data-nk; owned parts emit component-qualified data-slot values such as field-control or card-title. Select on those attributes, never on classes.
Customize components with documented --nk-* custom properties in an application stylesheet. Variables beginning with --_nk-* are private component mechanics.
Use NitroKit::Flex and NitroKit::Grid for layout. Parents own external placement and available width; components own their intrinsic geometry.
Preserve native elements and accessibility semantics. State is exposed through native semantics and ARIA first, and through data-state when styling or behavior also needs it.

Application navigation

Anatomy

Complete navigation

One destination

Two labelled groups

Collapsible groups

Pressure and composition

Long labels and dense badges

Item attributes and badge colors

Destination inventory

Under pressure

Hostile inventory

Component contract

Relevant patterns

Application foundation

System rules for coding agents