Nav

A row or column of links with a bar that slides to the current one.

SourcePackage @weft-js/warpPlayground

Preview

tsx

import { state } from '@weft-js/core'import { Nav } from '@weft-js/warp'export function Across() {  const at = state('Deploys')  const go = (e: Event, name: string) => { e.preventDefault(); at.value = name }  return (    <Nav label="Project">      {PAGES.map(name => <a key={name} href={`#${name}`} aria-current={at.value === name ? 'page' : undefined} onClick={e => go(e, name)}>{name}</a>)}    </Nav>  )}const PAGES = ['Overview', 'Deploys', 'Logs', 'Settings']

Installation

npm install @weft-js/warp

Usage

tsx

import { Nav } from '@weft-js/warp'

A column

axis="y" puts the bar beside the links.

tsx

import { state } from '@weft-js/core'import { Nav } from '@weft-js/warp'export function Down() {  const at = state('Deploys')  const go = (e: Event, name: string) => { e.preventDefault(); at.value = name }  return (    <Nav label="Project" axis="y">      {PAGES.map(name => <a key={name} href={`#${name}`} aria-current={at.value === name ? 'page' : undefined} onClick={e => go(e, name)}>{name}</a>)}    </Nav>  )}const PAGES = ['Overview', 'Deploys', 'Logs', 'Settings']

App header

Put Nav links beside a title, and set aria-current on the link for the current page.

tsx

import { state } from '@weft-js/core'import { Button, Heading, Nav, Row } from '@weft-js/warp'export function ProductHeader() {  const at = state('Deploys')  const go = (e: Event, name: string) => { e.preventDefault(); at.value = name }  return (    <Row justify="between" gap="section">      <Row gap="section">        <Heading level={3}>weft</Heading>        <Nav label="Main">          {PAGES.map(name => <a key={name} href={`#${name}`} aria-current={at.value === name ? 'page' : undefined} onClick={e => go(e, name)}>{name}</a>)}        </Nav>      </Row>      <Button size="sm" icon="rocket">Deploy</Button>    </Row>  )}const PAGES = ['Overview', 'Deploys', 'Logs', 'Settings']

Settings pages

Use axis="y" to stack the links down the side, with aria-current marking the current page.

tsx

import { state } from '@weft-js/core'import { Heading, Nav, Split, Stack, Text } from '@weft-js/warp'export function Settings() {  const at = state('General')  const go = (e: Event, name: string) => { e.preventDefault(); at.value = name }  return (    <Split side="start" width="rail" gap="section">      <Nav label="Settings" axis="y">        {['General', 'Domains', 'Billing', 'Team'].map(name => <a key={name} href={`#${name}`} aria-current={at.value === name ? 'page' : undefined} onClick={e => go(e, name)}>{name}</a>)}      </Nav>      <Stack gap="related">        <Heading level={3}>{at.value}</Heading>        <Text subtle>Everything about {at.value.toLowerCase()} for this project lives here.</Text>      </Stack>    </Split>  )}

spy lights the link whose heading is at the top of the window. Scroll to watch it move.

tsx

import { Heading, Nav, Split, Stack, Text } from '@weft-js/warp'export function Contents() {  return (    <Split side="start" width="rail" gap="section">      <Nav label="On this page" axis="y" spy>        <a href="#toc-build">Build</a>        <a href="#toc-deploy">Deploy</a>        <a href="#toc-roll-back">Roll back</a>      </Nav>      <Stack gap="section">        <Stack gap="tight"><Heading level={3} id="toc-build">Build</Heading><Text subtle>Every push runs your build command in a clean machine. Dependencies are cached between runs, so the second build is much faster than the first.</Text></Stack>        <Stack gap="tight"><Heading level={3} id="toc-deploy">Deploy</Heading><Text subtle>A finished build goes to each region in turn. New traffic moves over once the health check passes, and old requests are left to finish.</Text></Stack>        <Stack gap="tight"><Heading level={3} id="toc-roll-back">Roll back</Heading><Text subtle>Every deploy stays ready to serve. Promote an older one and traffic moves back in about ten seconds, with no new build.</Text></Stack>      </Stack>    </Split>  )}

When to use

Use it for

Links to the pages of an app or a section
A table of contents that follows the reader

Reach for something else

Tabs, when the views swap in place and have no URL
Menu, when the links run actions, or there are too many to show

Playground

Axis

import { Nav } from '@weft-js/warp'<Nav label="Project">  <a href="/overview">Overview</a>  <a href="/deploys" aria-current="page">Deploys</a>  <a href="/logs">Logs</a>  <a href="/settings">Settings</a></Nav>

Accessibility

Tab: Moves between links
Enter: Follows the link

label names the landmark, so a page with two navs can tell them apart.
The links are plain anchors. aria-current is what announces the page, as well as moving the bar.

API Reference

Prop	Type	Default	Description
`label`	`string`	—	The name of the navigation landmark.
`axis`	`"x" \| "y"`	`'x'`	`x` for a row, `y` for a column.
`spy`	`boolean`	`false`	Follow the headings the links point at, for a table of contents.
`children`	`unknown`	—	What it contains.

Parts

Every element carries a stable name, so you can style it from your own CSS: [data-scope="nav"] [data-part="indicator"]

indicator

RelatedTabs Link Shell