No matches.
component
ID or label of the currently active navigation item. Wins over `isItemActive` and `currentHref` when set.
What decides the active look. - `"prop"` (the default) — `activeItem`, resolved at render and baked as `data-panel-active`. - `"current"` — whatever element carries a truthy `aria-current` in the DOM. Nothing is baked and no `aria-current` is emitted; a client owns the state. This is the mode for a scroll-spy: the spy moves `aria-current` between links as the reader scrolls and the row styling follows with no re-render. `activeItem` is still honoured in `"current"` mode for seeding which submenus start open (`getDefaultOpenSubmenus`) — it just stops driving the visual state.
The router's current location, matched against each item's `href` to decide the active item (and so `aria-current="page"`). Pass the router's pathname — `useLocation().pathname`, `usePathname()`, `$page.url.pathname`, `Astro.url.pathname` — so the current row follows client-side navigation with no `activeItem` bookkeeping. Compared as an exact string against `String(item.href)`; use `isItemActive` for prefix or pattern matching. Ignored when `activeItem` is set; `isItemActive` wins over it.
ID of the item that owns the roving tabindex under `semantics: "menu"` — the single Tab stop the ARIA menubar pattern requires. Reactive input: the framework keyboard adapters own this state (it follows arrow-key navigation) and pass it in so `tabindex` mirrors stay live. When omitted (or pointing at a disabled/hidden item) the Tab stop falls back to the active item, then to the first enabled visible item — a pure function of props, so server and first client render always agree. Ignored under `semantics: "list"`, where native tab order is the model.
Router-driven active predicate: return `true` for the item the router considers current (e.g. `(item) => router.isActive(item.href)`). The first match in tree order becomes the active item, exactly as if its id had been passed as `activeItem`. Ignored when `activeItem` is set; wins over `currentHref`.
IDs of items whose submenu is currently visible — inline-expanded parents in an expanded vertical navigation, open flyouts otherwise. Reactive input: frameworks own this state and pass it in so `aria-expanded` / `data-submenu-open` mirrors stay live. Seed it with `getDefaultOpenSubmenus`.
Paint a parent row with the Panel active look while one of its descendants is the current item — the "where am I?" cue for rows whose active child is hidden. `"always"` keeps the cue in every state; `"compact"` shows it only while the rail is collapsed (`data-compact` present on the root), which is when the child is actually invisible. Omit for the default behavior (inline parents stay neutral; a closed flyout parent still takes the active look in `activeSource: "prop"` mode). Works with both `activeSource` modes: `"prop"` uses the baked `data-active-child` marker; `"current"` uses DOM detection — CSS for inline sublists, and (in Astro) a boot-script mirror for portaled flyout dialogs.
How loud the *current* item is, independent of the resting `emphasis`. Defaults to `"secondary"` — a tint on the `tone` ramp with promoted text and a lifted border, which marks the current row without shouting. Raise to `"primary"` for a filled brand row when the nav has to read at a glance, drop to `"tertiary"` for a colorless tint, or pick `"highlight"` to paint the current item with the `tone`'s highlight — the color selected items use (the current location otherwise stays on the surface tint). Under `appearance="tabs"` the strip is underline-only unless this is set: passing it explicitly gives the tabs hover/press fills and paints this surface under the current tab's bar.
The family the current item's highlight paints in, independent of `tone` — `"primary"` marks the current row in brand color while every other row (and its hover) stays neutral. Only read with `activeEmphasis: "highlight"`; any other level keeps `tone`.
Visual treatment of the item strip. `"tabs"` renders a minimal underline tab strip: transparent items, a 2px accent bar under (horizontal) or beside (vertical) the active item, and a 1px baseline track on the container. In this mode the per-item `border`/`borderInteract`/ `borderActive` props are ignored and `tone` defaults to `"primary"` so the bar picks up the accent color.
Background surface token painted on each **item** (not on the `<nav>` — see `rootBackground` for that). Panel derives every hover/press/active step from this resting position, so it is what makes a nav on a deep surface step the right way.
Resting border color of each item, by token level — Panel's `border`. Items reserve a 1px border at every level (including `"none"`), so switching levels or states never shifts layout.
Border color of the current item — Panel's `borderActive`. It holds while that item is hovered, so a `borderInteract` color can't steal it. `"inherit"` (the default) leaves the current row with the ring `activeEmphasis` chose; `"none"` explicitly clears it.
Item border color while hovered or pressed — Panel's `borderInteract`. Omitted (the default) keeps whatever `border` painted; `"none"` explicitly clears the line under the pointer. Any other level makes a border appear on hover only.
Resting emphasis of each item, on Panel's scale — every item IS a Panel, so this is Panel's `emphasis` verbatim. `"tertiary"` (the default) rests each row on the colorless neutral ramp; `"secondary"` tints it with the `tone` palette; `"primary"` makes every row a filled accent surface.
What hovering and pressing a row paints — Panel's `interactEmphasis`. `"surface"` (the default) steps the row's resting surface; `"highlight"` paints the `tone`'s highlight (`neutral.highlight` on the default neutral tone) and its next step while pressed, so a hovered row lights up off the page the way a current one does. The current row keeps its own hover steps.
Surface token for the `<nav>` element itself. The root is a Panel too, so a sidebar or topbar shell can be built from the component alone instead of a wrapper. Defaults to `"transparent"` — the nav has no chrome of its own unless you ask for it.
Border color of the `<nav>` element, by token level.
Corner radius of the `<nav>` element.
Frost the `<nav>`'s backdrop (for a nav floating over scrolling content).
`overflow="scroll"` only: a thin native scrollbar, or none (touchpads, touch, or with `scrollButtons`).
Size variant for the navigation; trailing badges scale with this value.
Color palette the items resolve their surfaces and text against. Stays `"neutral"` by default so labels read as text rather than as links — every other palette tints the resting rows' text too (Panel's `tertiary` colors it `colorPalette.text.accent`), which is rarely what a navigation wants. Set `"primary"` for a brand-forward navigation: the current row then picks up brand color, and `activeEmphasis` `"secondary"` / `"tertiary"` become visibly different levels (on the neutral palette they resolve to the same ramp).
Collapse the items to a narrow rail. `stack` shows icon over label with ellipsis; `icon` hides the label visually (kept for screen readers) and auto-wires the styled Tooltip from `item.label`.
What items' `media` becomes on the icon rail (`compact="icon"`, or a collapsed `compactToggle` rail). `"icon"` shrinks each picture to the rail's icon box, so a media row lines up with icon rows. `"media"` keeps it at its `mediaSize` — a rail of covers or avatars — and grows that row's square around it, inset like the expanded row. Rows without media keep the icon square either way; the stack rail always shrinks.
How a HORIZONTAL navigation handles a container narrower than its items (ignored — with a dev warning — on a vertical one): - `"none"`: items shrink and truncate their labels (the classic strip). - `"adapt"`: the strip follows its CONTAINER width (not the viewport) through progressive stages — full items; then labels truncate (the longest first, never below ~4em); then items fold to icon-only one at a time (lowest `priority` first, from the end; the active item last); then all icons. Folded items keep their accessible name and get an auto tooltip; a trailing count folds into a corner dot. Thresholds have hysteresis, so a resize never flip-flops an item. Only items with a `leading` icon fold. The server renders the full stage; the client adapts right after mount (before paint where the framework's effect timing allows) without animating that first pass. Ignored while the navigation is statically `compact`, and suspended while a `compactToggle` rail is collapsed. - `"scroll"`: the strip scrolls horizontally and never truncates: edge fades show only where more items hide, the active item scrolls into view on mount and on change, and roving keyboard focus keeps the focused item clear of the fades. See `scrollButtons` / `scrollbar`.
Inner padding of the `<nav>` element.
`overflow="scroll"` only: overlay an arrow button on each edge that still has items beyond it. Pointer-only (`tabindex="-1"`, `aria-hidden`) — keyboard users scroll by moving focus.
Placement config for the compact-mode trailing `<Attachment>` (the badge floating over a rail item). Pass `false` to disable it, so trailing content is simply not shown while compact. Overridable per item via `item.trailingAttachment`. Defaults to a corner badge on `strategy: "fixed"` so it is not clipped by a scrolling rail — pass `{ strategy: "absolute" }` to keep it inside the rail's layout instead.
When items' `actions` show: `"always"` keeps them visible; `"hover"` reveals them on row hover, focus inside the row, or while one of them is open (`aria-expanded="true"`), and always on a device without hover. A per-item `actionsReveal` wins.
Render the compact-safe structural superset so `compact` can be flipped at RUNTIME by toggling `data-compact="stack" | "icon"` on the root `<nav>` — no re-render needed (the pure-Astro animated collapse; the recipe keys all compact styling off that attribute and animates the morph). Semantics compared to a static `compact`: - Inline submenus stay inline: an expanded vertical navigation keeps its in-place child lists, and the rail squeezes them closed. Children stay reachable while collapsed through the RAIL FLYOUT: each parent also renders its children as a flyout panel (`railChildren` / `railFlyout*Props`), which the Astro boot opens on row hover/focus only while `data-compact` is present — a `linkableParent` keeps navigating on click. - `linkableParent` split rows stay rendered; the rail hides the disclosure and the anchor owns the square. - Styled tooltips ARE auto-derived from `item.label`, gated on the root's `data-compact` (`openWhen`) so they only fire while collapsed — matching what a static `compact` gives, without repeating a visible label when expanded. Because a tooltip is present, the native `title` fallback is dropped in both states. An explicit `item.tooltip` still fires in both states unless it opts into the same gate with `when: "compact"`, and `tooltip: false` still declines everything. - Trailing content renders inline only (the rail folds it away); the floating compact `<Attachment>` badge is not emitted. - `data-compact` reflects the initial `compact` prop; the component does not persist runtime state.
Grouped navigation items. Each entry renders a labelled group with an optional `title`. When provided, `items` is ignored and `api.items` is the flattened list of every section's items (back-compat).
How flyout submenus open in horizontal/compact mode. `"hover"` uses the Popover's hover-focus strategy with short open/close delays.
Which semantics the navigation exposes. - `"menu"` (the default) — an ARIA menu: `menubar` on the root, `menu` on sublists, `menuitem` on rows. Right for an application menu. - `"list"` — native navigation semantics: `<nav><ul><li><a>`, no menu roles. A submenu parent stays a disclosure button (`aria-expanded`), which is what it already is behaviourally, and `linkableParent` becomes available. `"list"` is the more accurate model for site navigation — a docs sidebar or table of contents is not an application menu, and `aria-current="page"` sits awkwardly on a `menuitem`. The default stays `"menu"` for back-compatibility.
Accessible name for a split row's disclosure button, derived from the item's label. A chevron alone names nothing, so the default is `` `Toggle ${label}` ``; pass a function to translate it. Per item, `item.submenuToggleLabel` wins over this.
Per-slot style and attribute override bag for the navigation's rendered elements.
Plus all standard <a> HTML attributes.