Nav

A side nav

The nav is named by its Title from the first render, so a screen reader's list of landmarks reads “Workspace navigation” without the words written twice. The current page is marked with current, and the stylesheet draws its line, weight and background from the aria-current attribute that sets. An icon is an svg before the text, aria-hidden and sized on it.

Nested lists

A List inside an Item indents a level, by --loam-nav-indent. The nesting is real list nesting, so a screen reader reports the level and the count at each.

Several sections

One Root carries one name, so a sidebar with several titled sections is one Root per section, stacked. The stylesheet spaces one Root from the next, and a screen reader lists each section as its own landmark, named by its Title.

Groups

A Group is a native details, so it folds without JavaScript and its title is a summary the keyboard already knows. Controlled here so the two groups share one open state; uncontrolled, pass defaultOpen, or share a name across groups and the browser keeps one open at a time. Close Reports and its title takes the marker: the current page is never folded out of sight.

Router links and other words

Link takes a router's link through render and the wiring (aria-current, the part's class) merges onto it. Without a Title the nav is named by labels.navigation, so a page in another language names its landmark in its own words.

Inline, for a header

The primitive is vertical; a horizontal nav is your flex row on the List, and --loam-nav-current-edge: block-end on the Root moves the current marker under the link. Everything else holds: the landmark's name, the current page's weight, the icons. Give a page's second nav an aria-label so the two are told apart.

Header with dropdowns

A Dropdown in an Item: the DropdownTrigger is a button set like the links beside it, with a chevron that turns, and the DropdownPanel is a native popover of ordinary links, anchored under the trigger and flipped by the browser at a viewport edge. Click opens it; Escape, a click outside or a Tab past the last link is the way out. Plants holds the current page, so its trigger takes the weight and, while closed, the marker. Learn is a wide panel: the same part, --loam-nav-dropdown-size raised on it and a grid of two Lists inside.

A line that opens a menu of actions

Destinations drop down from a Dropdown; a line that opens actions (switch workspace, sign out) is a Menu, whose items are commands with menu semantics and arrow keys. It is a button, not a link, so the reader is not promised a page. Render the Link as one and make it the Menu's trigger: Nav.Link gives it the part's class, Menu.Trigger the popup wiring (aria-haspopup, aria-expanded, the arrow keys), and the stylesheet sets a button carrying the link class like the links beside it, with no box, border or shadow of its own, the line's font and padding, the same hover and the same focus ring. Nothing to reset by hand. The example's chevron is an svg child, sized on the text like any icon.

A table of contents that follows the reader

useScrollSpy takes the headings' ids and returns the one in view. Scroll the text and the marker moves. The link says current="location", not page: the reader is still on this page, at a place within it, which is what aria-current="location" means. The list is the same Nav; only the current word changes.

Named from the first render

A page has several navs (a header, a sidebar, a table of contents, a footer column), and a screen reader lists them by name, so each needs one. One Root carries one name: a sidebar with several titled sections is one Root per section, stacked, and the stylesheet spaces them. The Root mints an id and points aria-labelledby at it in the server HTML; the Title renders that id, so the name is right before any JavaScript runs. If no Title registers, the reference is dropped after mount (a dangling aria-labelledby is an error) and labels.navigation names the nav instead. An aria-label or aria-labelledby you pass wins over both.

The current page is a line and a weight

current sets aria-current on the link, and the stylesheet draws the current line from that attribute: a bar on the start edge, a heavier weight and a subtle background. Three signals, so the state survives a flattened background, a colour-blind reader and forced colours, where the bar is drawn in the system highlight. The bar's space is reserved on every line by a transparent border, so marking a page never shifts its text.

The Link exists for its judgment

An <a> in an <li> needs no component. Nav.Link exists because it adds what a bare link leaves to memory: aria-current from a boolean, a class that styles whatever element render substitutes, an icon detected as a child, and the href forwarded either way. Pass a router's link through render and its own props win; the wiring merges on.

A group is a details element

Related links fold into a native details with a summary as its title, so the fold works before JavaScript, the keyboard already knows it, and the browser keeps one group open at a time when they share a name. open, defaultOpen and onOpenChange follow the library's controlled-or-not contract. A group holding the current page takes the weight on its title, and while closed the marker too, so where the reader is never disappears into a fold.

Vertical is the primitive; inline is a row

The List is a column. A header's horizontal nav is display: flex on the List in your own CSS, and nothing else changes: not the landmark, not the icons. The current marker is the one thing a row changes, since a bar on the start edge reads as a column's: --loam-nav-current-edge: block-end on the Root draws it under the link instead. A custom property, not a prop, because the edge is a fact of the layout around the nav, declared once where that layout is.

A dropdown is a disclosure, not a menu

A header's dropdown holds links, and a link is what a screen reader expects it to be: Tab reaches it, Enter follows it, the links list announces its count. A menu (role="menu", menuitem, aria-haspopup) promises something else: an application menu of commands, moved through with the arrow keys, where Tab leaves. Links wrapped in menu semantics lose their own and gain a keyboard model nobody asked for. So the DropdownTrigger is a button reporting aria-expanded and aria-controls, the DropdownPanel is a div with popover="auto" holding a List of ordinary Links, and the browser supplies the top layer, light dismiss and Escape. Menu remains the part for actions.

Click opens it; hover never does

A panel that opens on hover opens by accident: on the way to the link beside it, on the way across the header, and never for a keyboard, a touch screen or a switch. It closes the moment the pointer strays across the gap, and the code that mitigates that (delays, hit triangles) is guessing at intent. A click is a statement of it, from every input. The trigger opens the panel declaratively where the browser has commands (commandfor with command="toggle-popover"), through popovertarget where it has only that, and by its own click handler where it has neither; in all three, aria-expanded follows the panel's toggle event, so it says what the panel does. The panel is anchored under the trigger's start edge with CSS anchor positioning, flipped up or across when it would leave the viewport; without anchor positioning it is an absolutely positioned box under the Item, dismissed by the component. Focus stays on the trigger when the panel opens (Tab reaches the first link) and returns to it when the panel closes.

Page or location

current={true} says aria-current="page": the reader is on that page. A table of contents marks a place within the page, so it says current="location" instead; a wizard's steps say "step". The attribute is announced, and the stylesheet marks every value the same way, so choose the word that is true.

Nav.Root

The <nav> landmark; native <nav> props and ref are forwarded.

Nav.Title

A small label above the lists, a <p> by default; it renders the id that names the nav (yours if you pass one). Native props and ref are forwarded to the element rendered.

Nav.List

A <ul> with no markers, one line per Item. Nest one inside an Item to indent a level, or inside a Group to fold it. Native <ul> props and ref are forwarded.

Nav.Item

An <li> holding a Link or a Group, then an optional nested List. Native <li> props and ref are forwarded.

Nav.Link

A destination: an <a href> by default, with an svg child as its icon. Native <a> props (href, target, onClick) and ref are forwarded. Rendered as a <button> (a menu or popover's trigger among the links), it is set like the links beside it.

Nav.Group

A fold of related links: a native <details>. Native <details> props (name) and ref are forwarded.

Nav.GroupTitle

The group's always-visible line, a <summary> set like the links around it with a chevron at its end. Native <summary> props and ref are forwarded.

Nav.Dropdown

A dropdown of links opened from a line: context for a DropdownTrigger then a DropdownPanel, side by side inside an Item. Renders no element of its own.

Nav.DropdownTrigger

The line that opens the panel: a <button> carrying the link class, so it is set like the links beside it, with a chevron at its end that turns while the panel is open. It carries aria-expanded, aria-controls, popovertarget and commandfor with command="toggle-popover". Native <button> props and ref are forwarded.

Nav.DropdownPanel

A <div popover="auto"> anchored under the trigger, holding a List of Items and Links; a wide panel is your own grid of Lists inside it. Its width is --loam-nav-dropdown-size. Native <div> props and ref are forwarded.

useScrollSpy

Which of the elements with these ids is in view: the first, in the order given, that intersects the viewport, or the last one that did once none does (the reader is inside its section). null before anything has intersected, and on the server. One IntersectionObserver for the set, disconnected on unmount; a fresh array of the same ids does not re-observe.

const activeId = useScrollSpy(ids, options?);

Options: