ki-top-nav
@kimen/elements/ki-top-nav- Source
- Agent reference
Use ki-top-nav to group a brand, up to five primary destinations and global
actions. Use a sidebar for deeper navigation and ki-tabs for in-page views.
The navigation collapses into a menu when the header becomes narrower than
collapse-at, which defaults to 48rem of available width.
<ki-top-nav label="Workspace" collapse-at="24rem"><a slot="brand" href="#workspace">Kimen</a><a href="#overview" aria-current="page">Overview</a><a href="#projects">Projects</a></ki-top-nav>Keep a page-owned skip link first in the Tab order. Mark the current section
with aria-current="page". Name each icon button and include unread counts
in the notification button name, such as “Notifications, 3 unread”. Place the
visible ki-counter in the icon button’s counter slot.
Screen app bar
Use variant="app-bar" for a screen heading, a named leading control and
screen-specific actions. Set heading-level when the heading sits inside an
existing page outline. Use lg or xl for a separate title row, and
scroll-behavior="collapse" to move the heading into the main row on scroll.
Use sticky to keep the bar visible in its scroll container.
<ki-top-nav variant="app-bar" title="Release notes" subtitle="Version 2.4" size="lg"><ki-button slot="leading" variant="ghost" size="sm">Back</ki-button><ki-button slot="actions" variant="ghost" size="sm">Share</ki-button></ki-top-nav>Use named, directly slotted buttons or links for actions that can overflow.
The first three actions stay inline and later actions are available through
More actions. Supply a named control in the search slot to show the search
field and keep the screen heading in the accessibility tree.
API reference
When to use: group a brand, up to five primary sections and global controls, or set a screen title, leading control and screen actions in app-bar mode.
When not to use: more than five sections or a deep navigation tree (use a sidebar), or switches between in-page views (use ki-tabs).
Properties & attributes
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
collapse-at | collapseAt | string | '48rem' | CSS length below which navigation collapses and single-row app bars can center their title. |
heading-level | headingLevel | number | 1 | Native heading level for the screen title. Use 1 through 6 to fit the page outline. |
label | label | string | 'Main' | Accessible name of the header's primary navigation landmark. Override for localization. |
navigation-label | navigationLabel | string | 'Open navigation' | Accessible name for the compact navigation button and menu. Override for localization. |
overflow-label | overflowLabel | string | 'More actions' | Accessible name for the app-bar overflow button and menu. Override for localization. |
title | screenTitle | string | '' | Screen heading, set with the HTML title attribute or the screenTitle property. |
scroll-behavior | scrollBehavior | "collapse" | "elevate" | "none" | 'elevate' | Tint on scroll with elevate, also shrink tall bars with collapse, or opt out with none. |
size | size | "lg" | "md" | "sm" | "xl" | 'md' | Bar size. Only app-bar mode has large and extra-large two-row sizes. |
sticky | sticky | boolean | false | Keep the bar at the block start of the scroll container and draw a bottom border. |
subtitle | subtitle | string | '' | Supporting text displayed under the screen heading. |
title-align | titleAlign | "center" | "start" | 'start' | Center a compact single-row title when the app bar has at most one action. |
variant | variant | "app-bar" | "header" | 'header' | Header for primary navigation, or app-bar for the current screen. Defaults to header. |
Slots
| Slot | Description |
|---|---|
| (default) | Header mode: up to five direct native anchors; mark the current one with aria-current="page". |
actions | Header: global actions. App bar: up to three inline; additional direct named buttons or links go into overflow. |
brand | Header mode: the brand link or wordmark. |
leading | App bar: a named Back or Open navigation control. |
search | App bar: an accessible search control that can shrink inside its row. |
CSS parts
| Part | Description |
|---|---|
actions | Wrapper for the trailing actions. |
bar | Painted header or app-bar surface. |
brand | Wrapper for the header brand. |
heading | The native screen heading. |
leading | Wrapper for the app-bar leading control. |
links | Wrapper for the primary links, including when displayed as a menu. |
menu | Anchored navigation or overflow menu surface. |
menu-item | Generated screen action in the overflow menu. |
menu-trigger | Native button opening collapsed navigation or overflow. |
navigation | The named primary navigation landmark. |
search | Wrapper for the app-bar search control. |
subtitle | Supporting text below the screen heading. |
CSS custom properties
The public styling contract of ki-top-nav: reassign these tokens at :root or on a subtree — never override internals.
| Token | Description |
|---|---|
--ki-app-bar-backdrop-filter | Filter applied to the entire app-bar backdrop. |
--ki-app-bar-bg | Resting app-bar fill. |
--ki-app-bar-bg-image | Optional image above the app-bar fill. |
--ki-app-bar-fg | Resting app-bar title and control ink. |
--ki-app-bar-height | Height of a normal or collapsed app bar. |
--ki-app-bar-lg-height | Expanded height of a large app bar. |
--ki-app-bar-lg-title-size | Expanded two-row app-bar title size. |
--ki-app-bar-scrolled-bg | App-bar fill when its container scrolls. |
--ki-app-bar-scrolled-fg | App-bar title and control ink when its container scrolls. |
--ki-app-bar-scrolled-subtitle-fg | App-bar subtitle ink when its container scrolls. |
--ki-app-bar-subtitle-fg | Resting app-bar subtitle ink. |
--ki-app-bar-title-font-family | Screen heading typeface. |
--ki-app-bar-title-size | One-row app-bar title size. |
--ki-app-bar-xl-height | Expanded height of an extra-large app bar. |
--ki-density-target-min | The smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1). |
--ki-elevation-e3 | MarsUI Elevation/e3 (cumulative: e2 layers plus 0/20/20/-12). |
--ki-focus-ring-color | Colour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme. |
--ki-focus-ring-offset | Gap between a focusable component and its keyboard focus ring. |
--ki-focus-ring-width | Thickness of the keyboard focus ring every focusable component draws (its outline). One token instead of one per component, so a mode or a theme changes every ring at once. |
--ki-layout-border-width | Hairline edge on a structural surface. |
--ki-layout-indicator-width | Thickness of the line identifying a selected navigation destination. |
--ki-layout-spacing-12xl | The 12xl spacing step for a stack or grid gap. |
--ki-layout-spacing-7xl | The 7xl spacing step for a stack or grid gap. |
--ki-layout-spacing-xl | The xl spacing step for a stack or grid gap. |
--ki-layout-spacing-xs | The xs spacing step for a stack or grid gap. |
--ki-layout-touch-target | Minimum target dimension for navigation controls on a coarse pointer. |
--ki-motion-duration-fast | Fast interaction transition duration. |
--ki-motion-duration-medium-1 | M3 md.sys.motion.duration.medium1 (250ms). onmars: MarsUI moderate step (240ms, 2x the 120ms base). |
--ki-motion-easing-standard | Standard interaction transition easing curve. |
--ki-text-low-em | semantic color for text low em. Not an ink for body text: under 4.5:1 on the light surfaces (s0-s2). Use it for large text (24px, or 18.66px bold), icons and decoration; body text takes the high-em ink of the tone. |
--ki-top-nav-backdrop-filter | Filter applied to the entire header backdrop. |
--ki-top-nav-bg | Application header fill. |
--ki-top-nav-bg-image | Optional image above the header fill. |
--ki-top-nav-border | Edge color for sticky bars and menus. |
--ki-top-nav-fg | Application header brand and control ink. |
--ki-top-nav-height | Height of a normal application header. |
--ki-top-nav-height-compact | Height of a small application header. |
--ki-top-nav-indicator | Bar marking the current primary destination. |
--ki-top-nav-item-bg | Primary navigation item resting surface. |
--ki-top-nav-item-current-bg | Current navigation destination surface. |
--ki-top-nav-item-current-fg | Current navigation destination ink. |
--ki-top-nav-item-fg | Primary navigation item resting ink. |
--ki-top-nav-item-hover-bg | Hovered control or highlighted menu item surface. |
--ki-top-nav-item-hover-fg | Hovered control or highlighted menu item ink. |
--ki-top-nav-menu-radius | Menu and trigger corner radius. |
--ki-top-nav-padding-inline | Padding at the inline edges of both bars. |
--ki-typography-family-body | semantic font family for typography family body. |
--ki-typography-line-height-body-1 | semantic dimension for typography line height body 1. |
--ki-typography-line-height-heading-2 | semantic dimension for typography line height heading 2. |
--ki-typography-line-height-title-2 | semantic dimension for typography line height title 2. |
--ki-typography-size-body-1 | semantic dimension for typography size body 1. |
--ki-typography-size-title-2 | semantic dimension for typography size title 2. |
--ki-typography-visually-hidden-size | Nonzero edge for clipped text available to assistive technology. |
--ki-typography-weight-body-medium | semantic font weight for typography weight body medium. |
--ki-typography-weight-body-semibold | semantic font weight for typography weight body semibold. |
--ki-typography-weight-display-semibold | semantic font weight for typography weight display semibold. |