# App bar
The top bar of an application: brand, navigation links, then search, action buttons, the theme switch and the user, in five looks; the links fold into a menu when they do not fit.
Block: `smbk-app-bar`. Status: candidate. Figma: the Figma file, https://www.figma.com/community/file/1688324308358870630. Desktop and mobile: differ by presentation only.
## Options
| Axis | Values | Default | Meaning |
|---|---|---|---|
| `look` | `floating`, `floating-hug`, `flat`, `split`, `centred` | `floating` | Floating: a raised bar with rounded corners and a hairline edge, the links in the true middle. Floating hug: the same bar only as wide as its content, centered. Flat: a square bar with no edge or shadow, a line along its foot. Split: the brand on an island of its own at the start, the links and the end group on one at the end. Centred: the links at the start, the brand in the middle. Figma calls this Style. |
| `size` | `md`, `lg` | `md` | How large the links in the wide bar are. md is Figma's: the middle navigation item. lg is the large item, as the bar drew them before. The menu keeps its large items either way. |
| `background` | `on`, `off` | `on` | The bar's own surface. Off drops its fill, edge and shadow so it sits on whatever is behind it; the open menu keeps its surface, as Figma draws the open bar only with one, and a bar that hides on scroll takes the page's own surface while it sticks. Figma: Background (on by default). |
| `line` | `on`, `off` | `on` | The hairline along the foot of a flat bar. Only the flat look draws it. Figma: Line (on by default). |
| `logo` | `on`, `off` | `on` | The brand at the start of the bar in a wide space. Off drops it, for a page whose logo sits elsewhere, such as at the top of a sidebar that runs the page's full height; the links then start the bar, and a badge stays. The narrow bar keeps its logo either way. |
| `links` | `between`, `start`, `end` | `between` | Where the links sit in a wide space. Between: in the middle of the bar, as Figma draws it. Start: right after the brand, the free room after them, as the Showroom App bar draws them. End: pushed to the end, just before the search, buttons and theme switch, for a bar laid over a page whose middle is its own, such as a home page with a large picture behind it. Start and end are not in the App bar component in Figma. The menu is the same either way. |
| `nav-type` | `links`, `tabs` | `links` | How the wide bar draws its links. Links: navigation items. Tabs: small line tabs that fill the bar's whole height, the current page's underline on the bar's foot; the bar is then 64 tall. Either way they are links, the current one marked as the current page, and the menu lists them as navigation items. Figma: AppBarNav's Type. |
| `fold` | `none`, `actions`, `links` | `none` | What has folded away in a wide space too narrow for the whole row. Actions: the action buttons are gone. Links: the actions and the links are gone and the menu button shows, opening the links under the bar. The wrapper measures the row and sets it; markup written by hand sets it the same way. |
| `expanded` | on / off | off | The menu is open under the bar: in a narrow space, or in a wide one whose links have folded away. |
| `hide-on-scroll` | on / off | off | In a narrow space, the bar stays at the top of the window while the page scrolls, slides up out of sight as the reader scrolls down and comes back as they scroll up. For a page that scrolls the window; turned on page by page. Has no effect in a wide space. Not in Figma. |
| `scrolled-away` | on / off | off | The bar has slid up out of sight. The wrapper sets it while the reader scrolls down a page with hide on scroll on; plain markup sets it the same way. Has no effect without hide on scroll or in a wide space. |
| `zone` | on / off | off | The bar's own room, as Figma draws it: the medium inset above and below a floating bar and a step in from the sides, and its row held to the content width. Off by default, so a page that already leaves room around its bar keeps its own. |
| `sidebar-start` | on / off | off | In a wide space the start is as wide as the expanded sidebar, its logo the sidebar's logo size and in line with the sidebar's rows, so links that follow it (links start) begin where the page beside a sidebar begins. For a bar across the top of a page with a sidebar under it at the same side gutter as the bar's own inset. Not in the App bar component in Figma; drawn in the Showroom App bar. |
| `frosted` | on / off | off | A blur behind the bar, strongest at the top and gone by its foot, so what scrolls under it is never read sharply there. For a bar with its background off, or with its own room. Not drawn when the system asks for forced colors. |
Parts: `smbk-app-bar__panel`, `smbk-app-bar__frost`, `smbk-app-bar__bar`, `smbk-app-bar__start`, `smbk-app-bar__brand`, `smbk-app-bar__logo`, `smbk-app-bar__badge`, `smbk-app-bar__title`, `smbk-app-bar__trail`, `smbk-app-bar__nav`, `smbk-app-bar__end`, `smbk-app-bar__search`, `smbk-app-bar__actions`, `smbk-app-bar__divider`, `smbk-app-bar__menu-button`, `smbk-app-bar__second-row`, `smbk-app-bar__second-row-nav`, `smbk-app-bar__menu`, `smbk-app-bar__menu-end`, `smbk-app-bar__wide-only`, `smbk-app-bar__narrow-only`
## Markup
```html
⌘ K
```
## React
```tsx
import { AppBar } from './design-system/components/app-bar/app-bar.js';
import { SearchField } from './design-system/components/search-field/search-field.js';
import { Button } from './design-system/components/button/button.js';
import { ThemeSwitch } from './design-system/components/theme-switch/theme-switch.js';
import { Avatar } from './design-system/components/avatar/avatar.js';
{}} />} actions={
} themeSwitch={} user={} items={[{ label: "Home", href: "#home", icon: "House" }, { label: "Projects", href: "#projects", icon: "FolderSimple", active: true }, { label: "Reports", href: "#reports", icon: "ChartBar" }]} onSearch={() => {}} background="on" logo="on" links="between" look="floating" size="md" line="on" nav-type="links" fold="none" />
```
## Stylesheet
```css
/* smbk-app-bar — App bar. Figma "App bar" 7353:700 (Style × Platform × State), built from AppBarStart,
* AppBarNav and AppBarEnd.
* The top bar of an application: the start (the brand and a badge), the links in the middle, then at the end
* the search field, action buttons, the theme switch and the user. In a narrow space the links, search and
* actions give way to a search button and a menu button, and the menu button opens a stacked list under the
* bar. Which form shows is the layout switch, never a width written here. In a wide space too narrow for the
* whole row the wrapper folds the actions away, then the links, and the menu button opens them (fold).
*
* What the app bar shares with the header, which is built from the same parts, is written once in
* ../bar/bar.css: the bar and its surface, the five looks, the zone, the frost, the second row, the row's common
* arrangement and the open menu's movement. This stylesheet keeps what is the app bar's own. */
.smbk-app-bar__second-row {
padding: 0 calc(var(--smbk-space-inset-md) - var(--smbk-border-width-hairline)) calc(var(--smbk-space-inset-md) - var(--smbk-border-width-hairline));
}
.smbk-app-bar--look-split .smbk-app-bar__second-row {
padding: calc(var(--smbk-space-inset-md) - var(--smbk-border-width-hairline));
}
/* ==== The app bar's own row ==== */
/* Figma draws the bar's edge inside it (56 tall with a medium control between two medium insets), so each padding
here gives the edge's width back; the same in the narrow bar and its menu. The row clips what it cannot hold
until the page's script has measured it, so the page never scrolls sideways. */
.smbk-app-bar__bar {
display: flex;
justify-content: space-between;
gap: var(--smbk-space-inline-lg);
padding: calc(var(--smbk-space-inset-md) - var(--smbk-border-width-hairline));
}
/* The links sit in the true middle, as Figma draws them: the start and the end share what the links leave
equally; where there is too little room each end keeps what its content needs and the links move off the middle
rather than overlap. An end group holding a search field keeps the bar's room on either side of the links
instead, because there the search field narrows first. Markup without a start part keeps the room on either
side too. */
.smbk-app-bar__start,
.smbk-app-bar__start ~ .smbk-app-bar__trail > .smbk-app-bar__end {
flex: 1 1 0;
}
.smbk-app-bar__bar:has(.smbk-app-bar__search) > .smbk-app-bar__start {
flex: 0 0 auto;
}
.smbk-app-bar__badge {
display: inline-flex;
align-items: center;
flex-shrink: 0;
}
/* A title in the bar, after a back button at the start or alone in the middle, as Figma's AppBarStart Back and
AppBarNav Title draw it: Label LG in the default text color, on one line. */
.smbk-app-bar__title {
overflow: hidden;
color: var(--smbk-color-text-default);
font-family: var(--smbk-typography-label-lg-font-family);
font-size: var(--smbk-typography-label-lg-font-size);
font-weight: var(--smbk-typography-label-lg-font-weight);
line-height: var(--smbk-typography-label-lg-line-height);
letter-spacing: var(--smbk-typography-label-lg-letter-spacing);
text-transform: var(--smbk-typography-label-lg-text-transform);
text-overflow: ellipsis;
white-space: nowrap;
}
/* The links (their row is in bar.css) never shrink. */
.smbk-app-bar__nav {
flex-shrink: 0;
}
/* Links at the end: the free room goes before them instead of on either side, so they sit
against the end group, the bar's own gap apart. */
.smbk-app-bar--links-end .smbk-app-bar__nav {
margin-inline-start: auto;
}
.smbk-app-bar--links-end .smbk-app-bar__end,
.smbk-app-bar--links-end .smbk-app-bar__start ~ .smbk-app-bar__trail > .smbk-app-bar__end {
flex: 0 1 auto;
}
/* Everything after the links, the small inline step apart. When space runs short, the search field is what gives;
what still does not fit runs on past the end, where the bar clips it and its script sees it to fold, never back
over the logo (safe). */
.smbk-app-bar__end {
justify-content: safe flex-end;
flex: 0 1 auto;
min-width: 0;
}
/* Beside the links in the true middle, the end group keeps all it holds; it narrows only once everything that can
fold has folded. */
.smbk-app-bar__start ~ .smbk-app-bar__trail > .smbk-app-bar__end {
min-width: auto;
}
.smbk-app-bar__bar:has(.smbk-app-bar__search) .smbk-app-bar__end,
.smbk-app-bar--fold-links .smbk-app-bar__end {
flex: 0 1 auto;
min-width: 0;
}
.smbk-app-bar__search {
flex: 0 1 auto;
width: var(--smbk-size-search-width);
min-width: 0;
/* Narrowed past its icon and hint, it keeps them inside its own sides rather than over its neighbours; its
shadow still shows below it. */
overflow-x: clip;
}
.smbk-app-bar__actions {
display: flex;
align-items: center;
gap: var(--smbk-space-inline-sm);
flex-shrink: 0;
}
.smbk-app-bar__end > :not(.smbk-app-bar__search) {
flex-shrink: 0;
}
.smbk-app-bar__divider {
height: var(--smbk-size-control-md);
}
/* The open menu, as Figma's open mobile app bar draws it: the links with their icons, each row a medium control
tall and the extra-small stack step apart, then the theme switch at the end; the medium inset at the sides and
above the menu's foot, no dividers. */
.smbk-app-bar__menu {
gap: var(--smbk-space-stack-xs);
padding: 0 calc(var(--smbk-space-inset-md) - var(--smbk-border-width-hairline));
}
.smbk-app-bar__menu nav {
display: flex;
flex-direction: column;
gap: var(--smbk-space-stack-xs);
}
/* The theme switch at the menu's end shows only in the narrow form, where the bar has none of its own. */
.smbk-app-bar__menu-end {
display: none;
justify-content: flex-end;
}
/* ---- the looks' rows ---- */
/* Floating hug: none of the three places grows. */
.smbk-app-bar--look-floating-hug .smbk-app-bar__start,
.smbk-app-bar--look-floating-hug .smbk-app-bar__start ~ .smbk-app-bar__trail > .smbk-app-bar__end {
flex: 0 0 auto;
}
/* Split: each island has the bar's padding. */
.smbk-app-bar--look-split .smbk-app-bar__start,
.smbk-app-bar--look-split .smbk-app-bar__trail {
flex: 0 0 auto;
padding: calc(var(--smbk-space-inset-md) - var(--smbk-border-width-hairline));
}
.smbk-app-bar--look-split .smbk-app-bar__start ~ .smbk-app-bar__trail > .smbk-app-bar__end {
flex: 0 1 auto;
}
/* Centred: the links at the start, the brand in the middle, the end at the end. */
.smbk-app-bar--look-centred .smbk-app-bar__nav {
order: 1;
flex: 1 1 0;
}
.smbk-app-bar--look-centred .smbk-app-bar__start {
order: 2;
flex: 0 0 auto;
}
.smbk-app-bar--look-centred .smbk-app-bar__end {
order: 3;
}
/* ---- fold: in a wide space too narrow for the whole row, the actions go first, then the links, and the menu
button takes their place, opening the links under the bar. The wrapper measures and sets it. The selectors
carry the block so they outweigh the narrow form's rules for the menu button. ---- */
.smbk-app-bar--fold-actions .smbk-app-bar__actions,
.smbk-app-bar--fold-links .smbk-app-bar__actions,
.smbk-app-bar--fold-links .smbk-app-bar__nav {
display: none;
}
/* ---- the two forms (the shared parts are in bar.css): the open menu's foot padding after a fold. ---- */
.smbk-app-bar--fold-links.smbk-app-bar--expanded .smbk-app-bar__menu {
padding-bottom: calc(var(--smbk-space-inset-md) - var(--smbk-border-width-hairline));
}
/* Logo off: the wide bar starts with its links and keeps its end group at the end, even with no
links; a badge stays at the start. The narrow bar keeps its logo. */
.smbk-app-bar--logo-off .smbk-app-bar__brand,
.smbk-app-bar--logo-off .smbk-app-bar__start:not(:has(.smbk-app-bar__badge)) {
display: none;
}
.smbk-app-bar--logo-off .smbk-app-bar__start {
flex: 0 0 auto;
}
.smbk-app-bar--logo-off .smbk-app-bar__end {
margin-inline-start: auto;
}
@container style(--smbk-layout: narrow) {
.smbk-app-bar--logo-off .smbk-app-bar__brand {
display: inline-flex;
}
.smbk-app-bar--logo-off .smbk-app-bar__start:not(:has(.smbk-app-bar__badge)) {
display: flex;
}
}
/* ---- the wide bar's arrangements from the Showroom App bar (Figma 8061:17018). Each is wide only: the narrow bar
keeps its own form. ---- */
@container style(--smbk-layout: wide) {
/* Links start: the links right after the start and the free room after them, the start keeping only its own
width rather than sharing the room with the end. */
.smbk-app-bar--links-start .smbk-app-bar__start {
flex: 0 0 auto;
}
.smbk-app-bar--links-start .smbk-app-bar__nav {
margin-inline-end: auto;
}
/* Sidebar start: the start and the bar's gap after it as wide as the expanded sidebar, so the links begin at the
sidebar's edge; the logo a medium inset in, where the sidebar's rows begin, at the sidebar's own logo size. It
lines up when the bar's side inset is the page's gutter, as a flat bar's across a page with a medium inset
gutter is. */
.smbk-app-bar--sidebar-start .smbk-app-bar__start {
box-sizing: border-box;
flex: 0 0 auto;
width: calc(var(--smbk-size-sidebar-width) - var(--smbk-space-inline-lg));
padding-inline-start: var(--smbk-space-inset-md);
}
.smbk-app-bar--sidebar-start .smbk-app-bar__logo {
height: var(--smbk-size-icon-lg);
}
/* Nav type tabs: the links are small line tabs filling the bar's whole height, 64 with its edge, with no padding
above or below. The tabs reach over the bar's edge, so the current page's underline lies on the bar's foot line,
as Figma draws it; the bar's foot is their line, so the tabs draw none of their own. */
.smbk-app-bar--nav-type-tabs .smbk-app-bar__bar {
height: calc(var(--smbk-size-64) - 2 * var(--smbk-border-width-hairline));
padding-block: 0;
}
.smbk-app-bar--nav-type-tabs .smbk-app-bar__nav.smbk-tabs {
align-self: stretch;
align-items: stretch;
margin-block: calc(-1 * var(--smbk-border-width-hairline));
}
.smbk-app-bar--nav-type-tabs .smbk-app-bar__nav.smbk-tabs > .smbk-tabs__list {
height: auto;
box-shadow: none;
}
}
/* The narrow bar as Figma draws it: the medium inset all round, the row a medium control tall, the brand and the
end group at its two ends. */
@container style(--smbk-layout: narrow) {
.smbk-app-bar__bar {
padding: calc(var(--smbk-space-inset-md) - var(--smbk-border-width-hairline));
}
.smbk-app-bar__menu-end {
display: flex;
}
.smbk-app-bar--expanded .smbk-app-bar__menu {
padding-bottom: calc(var(--smbk-space-inset-md) - var(--smbk-border-width-hairline));
}
/* Floating hug: the places share the row. */
.smbk-app-bar--look-floating-hug .smbk-app-bar__start,
.smbk-app-bar--look-floating-hug .smbk-app-bar__start ~ .smbk-app-bar__trail > .smbk-app-bar__end {
flex: 1 1 0;
}
}
/* ---- hide on scroll: in a narrow space, a bar with the flag on stays at the top of the window, the
medium inset from its edge (the room a page leaves around its bar), over the page as it scrolls under it.
The wrapper marks it scrolled away while the reader scrolls down: it slides up past the window's edge,
by the gap above it and a large inset more so its shadow goes too, with the exit motion, and comes back
with the enter motion. It sticks inside the element around it, so that element must run the page's
length. At once under reduced motion. A wide space, where the page scrolls an inner area, keeps the
bar as it is. ---- */
@container style(--smbk-layout: narrow) {
.smbk-app-bar--hide-on-scroll {
position: sticky;
top: var(--smbk-space-inset-md);
z-index: var(--smbk-layer-sticky);
transition: translate var(--smbk-motion-enter-duration) var(--smbk-motion-enter-easing);
}
.smbk-app-bar--hide-on-scroll.smbk-app-bar--scrolled-away {
translate: 0 calc(-100% - var(--smbk-space-inset-md) - var(--smbk-space-inset-lg));
transition-duration: var(--smbk-motion-exit-duration);
transition-timing-function: var(--smbk-motion-exit-easing);
}
/* A flat bar runs edge to edge, so it sticks flush with the window's top, with no room above it. */
.smbk-app-bar--hide-on-scroll.smbk-app-bar--look-flat {
top: 0;
}
/* With its background off, a bar that sticks takes the page's own surface, still with no edge or shadow, so it
looks as it does at rest on the page while the page scrolls under it, and nothing shows through it. */
.smbk-app-bar--hide-on-scroll.smbk-app-bar--background-off:not(.smbk-app-bar--expanded) {
background: var(--smbk-color-surface-canvas);
}
}
@media (prefers-reduced-motion: reduce) {
.smbk-app-bar--hide-on-scroll {
transition: none;
}
}
/* While a page holds a bar that sticks, the window keeps the bar's room clear at its top whenever it
scrolls to bring something into view: a focused link, or a heading jumped to from a link to it. So
nothing lands under the bar. The room is the header height and the gap above the bar. In a wide
space, where the bar does not stick, the window keeps the same room, which only moves a jumped-to
heading a little further down. */
:root:has(.smbk-app-bar--hide-on-scroll) {
scroll-padding-block-start: calc(var(--smbk-size-header-height) + var(--smbk-space-inset-md));
}
/* The open menu starts from no height and no foot padding, so both grow (the movement is in bar.css). It comes
after the foot padding it replaces, which the starting style only overrides when it is the later rule. */
@starting-style {
.smbk-app-bar--expanded .smbk-app-bar__menu {
block-size: 0;
padding-bottom: 0;
}
}
```
## Tokens it reads
```json
{
"border-width": {
"hairline": {
"$type": "dimension",
"$value": "{{border-width.1}}",
"$description": "Thin lines: dividers and almost every edge."
}
},
"color": {
"border": {
"rim": {
"$type": "color",
"$value": "{{color.alpha.white.90}}",
"$description": "The light rim that makes a surface look lit: fields, chosen pills, cards."
},
"subtle": {
"$type": "color",
"$value": "{{color.grey.300}}",
"$description": "Dividers and quiet edges."
},
"focus": {
"$type": "color",
"$value": "{{color.red.600}}",
"$description": "Keyboard focus ring on controls."
}
},
"surface": {
"default": {
"$type": "color",
"$value": "{{color.grey.100}}",
"$description": "Standard surface: cards, panels, the header."
},
"canvas": {
"$type": "color",
"$value": "{{color.grey.200}}",
"$description": "Page background."
}
},
"text": {
"default": {
"$type": "color",
"$value": "{{color.grey.900}}",
"$description": "Main text."
}
}
},
"radius": {
"container": {
"sm": {
"$type": "dimension",
"$value": "{{radius.8}}",
"$description": "Corners of cards, panels and dialogs, small."
}
},
"control": {
"xs": {
"$type": "dimension",
"$value": "{{radius.2}}",
"$description": "Corners of controls, extra small."
}
}
},
"elevation": {
"raised": {
"$type": "shadow",
"$value": {
"light": "0px 2px 8px 1px #373d431a, 0px 1px 2px 0px #373d431a",
"dark": "0px 2px 8px 1px #00000026, 0px 1px 2px 0px #00000026"
}
}
},
"motion": {
"state": {
"duration": {
"$type": "duration",
"$value": "{{duration.200}}"
},
"easing": {
"$type": "cubicBezier",
"$value": "{{easing.cubic-in-out}}"
}
},
"enter": {
"duration": {
"$type": "duration",
"$value": "{{duration.320}}"
},
"easing": {
"$type": "cubicBezier",
"$value": "{{easing.expo-out}}"
}
},
"exit": {
"duration": {
"$type": "duration",
"$value": "{{duration.200}}"
},
"easing": {
"$type": "cubicBezier",
"$value": "{{easing.expo-in}}"
}
}
},
"space": {
"0": {
"$type": "dimension",
"$value": "0px",
"$description": "Raw space step, 0 px. Only for fixed distances inside a component; spacing that follows density uses space/inset, stack or inline."
},
"inset": {
"md": {
"$type": "dimension",
"$value": "{{space.8}}",
"$description": "Padding inside a component, medium."
},
"2xl": {
"$type": "dimension",
"$value": "{{space.24}}",
"$description": "Padding inside a component, 2× large."
},
"lg": {
"$type": "dimension",
"$value": "{{space.12}}",
"$description": "Padding inside a component, large."
}
},
"gutter": {
"xs": {
"$type": "dimension",
"$value": "{{space.8}}",
"$description": "A section’s outer side padding on a phone (space/layout/gutter points here). The page itself has no gutter: each section carries its own."
}
},
"stack": {
"sm": {
"$type": "dimension",
"$value": "{{space.8}}",
"$description": "Gap between things stacked one above another, small."
},
"md": {
"$type": "dimension",
"$value": "{{space.12}}",
"$description": "Gap between things stacked one above another, medium."
},
"xs": {
"$type": "dimension",
"$value": "{{space.4}}",
"$description": "Gap between things stacked one above another, extra small."
}
},
"inline": {
"lg": {
"$type": "dimension",
"$value": "{{space.12}}",
"$description": "Gap between things side by side, large."
},
"md": {
"$type": "dimension",
"$value": "{{space.8}}",
"$description": "Gap between things side by side, medium."
},
"xs": {
"$type": "dimension",
"$value": "{{space.4}}",
"$description": "Gap between things side by side, extra small."
},
"sm": {
"$type": "dimension",
"$value": "{{space.6}}",
"$description": "Gap between things side by side, small."
},
"2xl": {
"$type": "dimension",
"$value": "{{space.24}}",
"$description": "Gap between things side by side, 2× large."
}
}
},
"size": {
"64": {
"$type": "dimension",
"$value": "64px",
"$description": "Raw size step, 64 px. Only for fixed sizes inside a component; semantic sizes (size/control, icon, mark) point here."
},
"layout": {
"container": {
"default": {
"$type": "dimension",
"$value": "{{size.layout.container.3xl}}",
"$description": "The default page container max width: 3xl, 1360 px. Full width (the space available) is the Fill sizing in Figma and size/layout/container/full (100%) in code, which Figma cannot hold as a number."
}
}
},
"control": {
"md": {
"$type": "dimension",
"$value": "{{size.40}}",
"$description": "Height of a medium control, where controls insert by default: 40 comfortable, 32 compact. Dashboard recipe: use compact density; 40 for the page’s one main action and for forms; 32 for toolbars and filters, the size used most; 28 for actions inside table rows and cards. On phones switch to comfortable density, or give small controls an invisible 44 px tap area (size/target/comfortable)."
}
},
"icon": {
"xl": {
"$type": "dimension",
"$value": "{{size.32}}",
"$description": "Icon box, extra large."
},
"lg": {
"$type": "dimension",
"$value": "{{size.24}}",
"$description": "Icon box, large."
}
},
"target": {
"comfortable": {
"$type": "dimension",
"$value": "{{size.44}}",
"$description": "Comfortable touch target (44)."
}
},
"search": {
"width": {
"$type": "dimension",
"$value": "320px",
"$description": "Width of the search field in the wide app bar. A fixed frame width in Figma with no variable behind it; it should become one."
}
},
"sidebar": {
"width": {
"$type": "dimension",
"$value": "280px",
"$description": "Width of the expanded sidebar. Not a step on any primitive scale."
}
},
"header": {
"height": {
"$type": "dimension",
"$value": "{{size.56}}",
"$description": "The sticky header’s height, for scroll padding so a focused item is never hidden under it: 56 on a phone, 80 on a desktop. Each value points to a density token, so compact density still applies."
}
}
},
"blur": {
"4": {
"$type": "dimension",
"$value": "4px",
"$description": "Raw blur, 4 px."
},
"8": {
"$type": "dimension",
"$value": "8px",
"$description": "Raw blur, 8 px."
},
"14": {
"$type": "dimension",
"$value": "14px",
"$description": "Raw blur, 14 px."
}
},
"focus": {
"ring": {
"width": {
"$type": "dimension",
"$value": "{{border-width.2}}",
"$description": "Thickness of the focus ring."
},
"offset": {
"$type": "dimension",
"$value": "{{space.2}}",
"$description": "Gap between a control and its focus ring."
}
}
},
"typography": {
"label-lg": {
"$type": "typography",
"$value": {
"fontFamily": "Geist, Geist Fallback, system-ui, sans-serif",
"fontSize": "16px",
"fontWeight": 500,
"lineHeight": 1.4,
"letterSpacing": "0px"
},
"$description": "Label LG: labels on controls and short UI text (buttons, chips, tabs, menu headings). Geist Medium, sentence case. Code and keys use Code SM and Code MD."
}
},
"layer": {
"sticky": {
"$type": "number",
"$value": 1100
}
}
}
```
## Purpose
The bar across the top of an application screen: the brand, the main links, and at the end a search field, a couple of action buttons, the theme switch and the signed-in user. It is for a product someone is working in. The header is its cousin for a marketing or documentation site; the two share their looks and their parts.
## Anatomy
- The block, a raised bar with a hairline edge. With the background off it has no fill, edge or shadow and sits on the page behind it; the open menu keeps its surface.
- Five looks: floating (the default), floating hug (only as wide as its content, centered), flat (square, no edge or shadow, a hairline along its foot that the line setting turns off), split (the start on an island of its own, the links and the end on another) and centred (the links at the start, the brand in the middle).
- The panel part: the bar's surface when the bar has its own room or a frost; otherwise it is no box and the block draws the surface.
- The bar part, the row: the start part (the brand part with the logo part, then an optional badge part), the trail part holding the nav part (navigation items with their icons and any count or dot, the same links drawn as line tabs, or other content in their place) and the end part (the search part, the actions part, the theme switch and the user; a search button, in a narrow space, or in a wide one with no search field; and in a narrow space or once the links have folded the menu button part).
- The logo part is the built-in simbolik logo, or a site's own picture files with their dark versions (`logoPicture`, the logo's `picture`): the whole logo in a wide space and the mark in a narrow one. Anything else goes in the brand's place (`brand`), or in the whole start's place (`start`), such as a back button and a title part.
- The second row part, under the bar: a divider and the second row nav part, a row a control tall for further navigation such as line tabs.
- The menu part, under the bar when expanded: the links as large navigation items each filling its row, and in a narrow space the theme switch at the end.
- The frost parts, three layers behind the bar when frosted.
## When to use
- The top of every screen of an application.
## When not to use
- A website. Use the [header](header.md), which has the same looks.
- Inside a page. It is page chrome, not content.
## Behavior
One markup serves both forms. In a wide space the links sit in the true middle of the bar: the start and the end share what the links leave equally, and where there is too little room each end keeps what it holds and the links move off the middle rather than overlap. Set to the start, the links follow the start and the free room comes after them. Set to the end, the links sit against the end group. An end group holding a search field keeps the same room on either side of the links instead, and there the search field narrows first. In a narrow space the links, the search field and the action buttons are removed and replaced by a search button and a menu button, and the menu button stacks the links under the bar. The form follows the layout switch, so a wrapper can force either. The menu state can be controlled from outside or left to the bar. Escape closes the open menu and puts focus back on the menu button. The menu grows open under the bar with the enter motion and closes a little faster with the exit motion; under reduced motion it opens and closes at once.
In a wide space too narrow for the whole row, the bar folds parts away rather than cutting them off: first the action buttons, then the links, whose place the menu button takes; it opens them under the bar. The bar measures its own row whenever its size or content changes and once the fonts have loaded, and keeps the least folded form that fits, so the links come back as soon as there is room. Only links fold: content passed in their place stays. Before the page's script runs the row clips what it cannot hold, so the page never scrolls sideways. `fold={false}` keeps every part in the row; a stage (`"actions"`, `"links"`) holds the bar there. Markup written by hand sets the fold modifier itself.
The bar can have its own room (`zone`): the medium inset above and below a floating bar and a step in from the sides, a smaller one in a narrow space, and none around a flat bar; past the content width its row stays that wide and centered while the surface runs on. It is off by default, so a page that already leaves room around its bar keeps its own. A frosted bar has a blur behind it, strongest at the top and gone by its foot, so what scrolls under it is never read sharply there; it shows where the bar has no background of its own, or in its room, and is not drawn when the system asks for forced colors.
The links can be drawn as tabs (`nav-type="tabs"`): small line tabs that fill the wide bar's whole height, the current page's brand underline lying on the bar's foot, the bar then 64 tall. They are still links, the current page marked, and the menu lists them as navigation items as before. Over a page with a sidebar under the bar, the start can be as wide as the expanded sidebar (`sidebar-start`), its logo the sidebar's logo size and in line with the sidebar's rows, so links set to the start begin at the sidebar's edge. That lines up when the bar's side inset is the page's gutter, as a flat bar's across a page with the medium inset gutter is. Both change the wide bar only.
The logo can be turned off for the wide bar, for a page whose logo sits elsewhere, such as at the top of a sidebar that runs the page's full height: the links then start the bar, a badge stays, and the end group keeps its place. The narrow bar keeps its logo whatever the setting, because there the page's other logo is usually gone with its sidebar.
A page that scrolls the window can turn on hide on scroll, page by page. In a narrow space the bar then stays at the top of the window while the page scrolls under it, slides up out of sight as the reader scrolls down, and comes back as soon as they scroll up, so the menu and search are never more than a small scroll away. It ignores moves of a few pixels, stays while the page is still within the bar's own height of the top, never hides while one of its menus is open or keyboard focus is inside it, and comes back the moment keyboard focus moves into it. It slides away with the exit motion and back with the enter motion; under reduced motion it hides and shows at once. A flat bar sticks flush with the window's top, and a bar with its background off takes the page's own surface while it sticks, still with no edge or shadow, so nothing shows through it. While such a bar is on the page, the window keeps the bar's room clear at its top whenever it scrolls to bring something into view, a link reached with Tab or a heading jumped to, so nothing lands under the bar. A wide space keeps the bar as it is. A page that is one screen by design, such as a home page, leaves it off.
A page can take the menu over (`onMenu`): the menu button then calls the page instead of opening the bar's own menu, and the bar draws no menu, so the page opens its own, such as a drawer holding the links and more. The button then says it opens a dialog rather than that it is expanded. On a phone, for example, a drawer can hold the site's sections and its whole category tree, with the theme switch in the drawer's foot.
Hide on scroll needs the bar to stick to the top of the window, and a sticking element cannot leave the element around it. Place the bar straight in the page's column, or give a wrapper that holds only the bar `display: contents` in a narrow space.
## Accessibility
### What it does for you
- The bar is a banner landmark. The links in the bar are a navigation landmark named "Main" by default, and the menu links one named "Menu". Drawn as tabs they are the same links in the same navigation, never a tab list.
- A link's count and dot are part of its name, after a pause: "Issues, 18".
- The current page's link carries the current-page marker, and its label is a weight step bolder as well as filled.
- The menu button carries its expanded state and names the menu it controls; the search button is named "Search". Escape closes the open menu and returns focus to the menu button.
- Parts hidden by the layout switch or folded away are removed from the tab order, so nothing is reachable that cannot be seen.
- A badge after the brand is read after it.
- In the centred look the brand is still first in reading and Tab order, before the links that are drawn to its left.
- A bar that has scrolled out of sight comes back the moment keyboard focus moves into it, and stays while focus is inside it, so a keyboard user never works in a bar they cannot see.
### What you must do
- Give the links another name when a page has more than one bar.
- Put something with an accessible name in the user slot, for example an avatar with the person's name.
- Give the words the bar says by itself, such as the menu button's and the search button's names, in the page's own language. They keep their English unless the page gives its own.
### How to test
- Tab through the bar: focus moves in the order it is read, the focus ring shows in both themes and in a forced-color mode, and nothing hidden takes focus.
- Open the menu with Enter or Space, then press Escape: it closes and focus is back on the menu button.
- With a screen reader, the bar is read as a banner with a "Main" navigation, the current page is announced as current, and a link's count is read after its label.
- With text at 200% and the page 320 pixels wide, the bar folds to its menu and every link stays reachable.
- On a page that scrolls, scroll the bar out of sight, then Tab into it: it comes back.
### Keyboard
| Key | What it does |
|---|---|
| Tab | Moves focus through the visible links and buttons in reading order. |
| Shift + Tab | Moves focus back through them. |
| Enter | Follows a link, or presses the menu button or the search button. |
| Space | Presses the menu button or the search button. |
| Escape | Closes the open menu and returns focus to the menu button. |
## Usage rules
### Do
- Give the user slot a way to sign out.
- Keep the links to the few that matter most; the same list fills the menu.
- Give every link an icon, or none.
- Turn on the bar's own room only where the page leaves none around it, so the space is never doubled.
### Don't
- Put more than two or three action buttons in it. Move the rest behind a menu.
- Rely on the action buttons in a narrow space or a crowded wide one: they fold away, so anything they do must be reachable elsewhere too.
