Navigation & layoutBrick 0.1.2

Nav List

Nav List renders finished native navigation lists, current destinations, and optional grouped disclosure sections on Atom NavList behavior.

Live example

Built from the published package

Interactive

Choose with confidence

Know when Nav List is the right part

Use it when

Use Nav List for sidebar destinations, settings sections, documentation indexes, and grouped route lists in a page, Sidebar, or Drawer.

Choose another path when

Use Link for one destination, Button for action-styled navigation, Navigation Menu for flyouts, Tabs for panel selection, and List for non-navigation content. Nav List does not own routing, scrollspy, Sidebar layout, or Drawer switching.

Installation and imports

tsx

import { NavList } from "@flowstack-ui/brick/nav-list";
import "@flowstack-ui/brick/styles.css";

The complete stylesheet above is the recommended default. For a measured route-aware build, replace it with the shared foundation and this component's stylesheet:

tsx

import "@flowstack-ui/brick/styles/core.css"; // once at the application root
import "@flowstack-ui/brick/styles/nav-list.css";

Add the modular stylesheet for every other Brick component the route renders. Do not combine modular styles with styles.css or tokens.css.

Nav List is also exported from @flowstack-ui/brick.

Quick start

tsx

<NavList.Root aria-label="Settings">
  <NavList.List>
    <NavList.Item>
      <NavList.Link active href="/profile">Profile</NavList.Link>
    </NavList.Item>
    <NavList.Item>
      <NavList.Link href="/security">Security</NavList.Link>
    </NavList.Item>
  </NavList.List>
</NavList.Root>

Visual recipes and states

The default soft accent recipe gives the current destination a quiet accent surface and semibold label. Solid uses a filled current row; outline uses a current border. Neutral changes current/open emphasis to the neutral family. Size coordinates row target, padding, text, icons, descriptions, and group indentation.

Hover, pressed, current, open, focus-visible, and disabled remain distinct. Current state comes from Atom active/aria-current; Brick never compares URLs. Vertical links fill their track. Horizontal links remain content-sized and wrap.

Root emits data-variant, data-tone, and data-size for visual recipes.

Examples

Grouped disclosure navigation

tsx

<NavList.Root aria-label="Documentation">
  <NavList.Section collapsible defaultOpen>
    <NavList.SectionLabel as="h2">Foundations</NavList.SectionLabel>
    <NavList.SectionTrigger>Foundations</NavList.SectionTrigger>
    <NavList.SectionContent>
      <NavList.List>
        <NavList.Item>
          <NavList.Link href="/tokens" description="Color and spacing">
            Tokens
          </NavList.Link>
        </NavList.Item>
      </NavList.List>
    </NavList.SectionContent>
  </NavList.Section>
</NavList.Root>

Router composition

tsx

<NavList.Link asChild active>
  <RouterLink to="/projects">Projects</RouterLink>
</NavList.Link>

Routing and active-route derivation remain application-owned.

Public contract

API

Start with the public parts and root options below. Components with multiple parts separate each area into its own named subsection.

Root recipes

Prop	Values	Default
`variant`	`soft`, `solid`, `outline`	`soft`
`tone`	`accent`, `neutral`	`accent`
`size`	`sm`, `md`, `lg`	`md`
`orientation`	`vertical`, `horizontal`	`vertical`

Link additions

Prop	Type	Default
`children`	`ReactNode`	required
`startIcon`	`ReactNode`	none
`endIcon`	`ReactNode`	none
`description`	`ReactNode`	none

Link also preserves Atom href, active, current, disabled, aria-current, render, and asChild. asChild delegates all content and therefore cannot be combined with the three Brick anatomy props.

List preserves ordered. Section preserves collapsible, open, defaultOpen, onOpenChange, and disabled. SectionLabel preserves as="h2|h3|h4|h5|h6|div". SectionContent preserves forceMount. Every part preserves native props, class, style, slot, ref, render, and asChild.

Shared responsibility

Accessibility

Give each navigation landmark a distinguishable aria-label or aria-labelledby when a page has more than one. Links retain normal Tab and Enter behavior. Collapsible triggers retain native button Enter/Space behavior, generated expanded/control relationships, and focus.

Nav List deliberately adds no menu/tree roles, roving focus, arrow keys, or typeahead. Current destinations expose aria-current; disabled links cannot navigate. Heading levels remain consumer-selected. Focus, current state, and disabled state remain visible in forced colors.

Responsive behavior

Nav List introduces no breakpoint, panel, maximum height, or scroll owner. Vertical rows wrap long labels and descriptions. Horizontal navigation wraps without equal-width items. A containing Sidebar, Drawer, or Scroll Area owns its responsive and overflow policy.

Stable visual contract

Styling and tokens

Customization

tsx

<NavList.Root
  aria-label="Projects"
  style={{
    "--brick-nav-list-row-radius": "0.25rem",
    "--brick-nav-list-content-inset": "1.5rem",
  }}
>
  {/* destinations */}
</NavList.Root>

Prefer closed recipes first. Use public variables for deliberate local themes.

Tokens and CSS hooks

Part classes are .brick-nav-list, .brick-nav-list__list, .brick-nav-list__item, .brick-nav-list__link, .brick-nav-list__section, .brick-nav-list__section-label, .brick-nav-list__section-trigger, and .brick-nav-list__section-content.

Link anatomy adds __link-start, __link-content, __link-label, __link-description, and __link-end.

Public variables include --brick-nav-list-gap, --brick-nav-list-section-gap, --brick-nav-list-item-gap, --brick-nav-list-content-inset, --brick-nav-list-row-min-block-size, row padding/radius, link foreground/surface state variables, --brick-nav-list-current-border, --brick-nav-list-focus-ring, icon size/gap, description foreground, label typography aliases, and --brick-nav-list-trigger-indicator-size.

Advanced reference

Open these details only when you need to inspect DOM ownership, native forwarding, or lower-level composition.

Maintainer resources

Tests, playground evidence, source notes, and release history remain available without crowding the plug-and-play guide.

Source docs Changelog Playground