Skip to content
Kimenpre-v1documentation home
Color scheme

ki-top-nav

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.

Theme for this example
Color scheme for this example
<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.

Theme for this example
Color scheme for this example
Back Share
<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

AttributePropertyTypeDefaultDescription
collapse-atcollapseAtstring'48rem'CSS length below which navigation collapses and single-row app bars can center their title.
heading-levelheadingLevelnumber1Native heading level for the screen title. Use 1 through 6 to fit the page outline.
labellabelstring'Main'Accessible name of the header's primary navigation landmark. Override for localization.
navigation-labelnavigationLabelstring'Open navigation'Accessible name for the compact navigation button and menu. Override for localization.
overflow-labeloverflowLabelstring'More actions'Accessible name for the app-bar overflow button and menu. Override for localization.
titlescreenTitlestring''Screen heading, set with the HTML title attribute or the screenTitle property.
scroll-behaviorscrollBehavior"collapse" | "elevate" | "none"'elevate'Tint on scroll with elevate, also shrink tall bars with collapse, or opt out with none.
sizesize"lg" | "md" | "sm" | "xl"'md'Bar size. Only app-bar mode has large and extra-large two-row sizes.
stickystickybooleanfalseKeep the bar at the block start of the scroll container and draw a bottom border.
subtitlesubtitlestring''Supporting text displayed under the screen heading.
title-aligntitleAlign"center" | "start"'start'Center a compact single-row title when the app bar has at most one action.
variantvariant"app-bar" | "header"'header'Header for primary navigation, or app-bar for the current screen. Defaults to header.

Slots

SlotDescription
(default)Header mode: up to five direct native anchors; mark the current one with aria-current="page".
actionsHeader: global actions. App bar: up to three inline; additional direct named buttons or links go into overflow.
brandHeader mode: the brand link or wordmark.
leadingApp bar: a named Back or Open navigation control.
searchApp bar: an accessible search control that can shrink inside its row.

CSS parts

PartDescription
actionsWrapper for the trailing actions.
barPainted header or app-bar surface.
brandWrapper for the header brand.
headingThe native screen heading.
leadingWrapper for the app-bar leading control.
linksWrapper for the primary links, including when displayed as a menu.
menuAnchored navigation or overflow menu surface.
menu-itemGenerated screen action in the overflow menu.
menu-triggerNative button opening collapsed navigation or overflow.
navigationThe named primary navigation landmark.
searchWrapper for the app-bar search control.
subtitleSupporting 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.

TokenDescription
--ki-app-bar-backdrop-filterFilter applied to the entire app-bar backdrop.
--ki-app-bar-bgResting app-bar fill.
--ki-app-bar-bg-imageOptional image above the app-bar fill.
--ki-app-bar-fgResting app-bar title and control ink.
--ki-app-bar-heightHeight of a normal or collapsed app bar.
--ki-app-bar-lg-heightExpanded height of a large app bar.
--ki-app-bar-lg-title-sizeExpanded two-row app-bar title size.
--ki-app-bar-scrolled-bgApp-bar fill when its container scrolls.
--ki-app-bar-scrolled-fgApp-bar title and control ink when its container scrolls.
--ki-app-bar-scrolled-subtitle-fgApp-bar subtitle ink when its container scrolls.
--ki-app-bar-subtitle-fgResting app-bar subtitle ink.
--ki-app-bar-title-font-familyScreen heading typeface.
--ki-app-bar-title-sizeOne-row app-bar title size.
--ki-app-bar-xl-heightExpanded height of an extra-large app bar.
--ki-density-target-minThe 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-e3MarsUI Elevation/e3 (cumulative: e2 layers plus 0/20/20/-12).
--ki-focus-ring-colorColour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme.
--ki-focus-ring-offsetGap between a focusable component and its keyboard focus ring.
--ki-focus-ring-widthThickness 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-widthHairline edge on a structural surface.
--ki-layout-indicator-widthThickness of the line identifying a selected navigation destination.
--ki-layout-spacing-12xlThe 12xl spacing step for a stack or grid gap.
--ki-layout-spacing-7xlThe 7xl spacing step for a stack or grid gap.
--ki-layout-spacing-xlThe xl spacing step for a stack or grid gap.
--ki-layout-spacing-xsThe xs spacing step for a stack or grid gap.
--ki-layout-touch-targetMinimum target dimension for navigation controls on a coarse pointer.
--ki-motion-duration-fastFast interaction transition duration.
--ki-motion-duration-medium-1M3 md.sys.motion.duration.medium1 (250ms). onmars: MarsUI moderate step (240ms, 2x the 120ms base).
--ki-motion-easing-standardStandard interaction transition easing curve.
--ki-text-low-emsemantic 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-filterFilter applied to the entire header backdrop.
--ki-top-nav-bgApplication header fill.
--ki-top-nav-bg-imageOptional image above the header fill.
--ki-top-nav-borderEdge color for sticky bars and menus.
--ki-top-nav-fgApplication header brand and control ink.
--ki-top-nav-heightHeight of a normal application header.
--ki-top-nav-height-compactHeight of a small application header.
--ki-top-nav-indicatorBar marking the current primary destination.
--ki-top-nav-item-bgPrimary navigation item resting surface.
--ki-top-nav-item-current-bgCurrent navigation destination surface.
--ki-top-nav-item-current-fgCurrent navigation destination ink.
--ki-top-nav-item-fgPrimary navigation item resting ink.
--ki-top-nav-item-hover-bgHovered control or highlighted menu item surface.
--ki-top-nav-item-hover-fgHovered control or highlighted menu item ink.
--ki-top-nav-menu-radiusMenu and trigger corner radius.
--ki-top-nav-padding-inlinePadding at the inline edges of both bars.
--ki-typography-family-bodysemantic font family for typography family body.
--ki-typography-line-height-body-1semantic dimension for typography line height body 1.
--ki-typography-line-height-heading-2semantic dimension for typography line height heading 2.
--ki-typography-line-height-title-2semantic dimension for typography line height title 2.
--ki-typography-size-body-1semantic dimension for typography size body 1.
--ki-typography-size-title-2semantic dimension for typography size title 2.
--ki-typography-visually-hidden-sizeNonzero edge for clipped text available to assistive technology.
--ki-typography-weight-body-mediumsemantic font weight for typography weight body medium.
--ki-typography-weight-body-semiboldsemantic font weight for typography weight body semibold.
--ki-typography-weight-display-semiboldsemantic font weight for typography weight display semibold.

Open TopNav in Storybook