Side Nav

Preview

Installation

pnpm add @oshon-ai/components @oshon-ai/tokens @oshon-ai/primitives

pnpm dlx @oshon-ai/cli add sidenav

Wire the tokens into your Tailwind v4 stylesheet:

/* app/globals.css */
@import 'tailwindcss';
@import '@oshon-ai/tokens/css';
@import '@oshon-ai/tokens/tailwind';

New here? Walk through the full setup — prereqs, theming, your first render.

Usage

Import the component and render it. Every component supports the standard tier, size, and disabled props where applicable.

'use client';
import { SideNav } from '@oshon-ai/components';

export default function Example() {
  return <SideNav />;
}

<div style={{ height: '520px', display: 'flex' }}>
      <SideNav size="m" collapsed={true} />
    </div>

<div style={{ display: 'flex', flexDirection: 'column', gap: '1rem', alignItems: 'flex-start' }}>
      <div key="m" data-story-size="m">
        <div style={{ height: '520px', display: 'flex' }}>
          <SideNav size="m" collapsed={true} />
        </div>
      </div>
    </div>

API

Every prop is documented here directly from the component's TypeScript interface. Inherited DOM attributes (aria-*, onClick, style, etc.) work as usual but are omitted from this table.

Styling

Three layers of customization, in order of escape-hatch strength: className overrides → data-attribute targeting → CSS custom properties.

Passing Tailwind classes

Every Oshon component accepts a className prop merged AFTER the component's default classes. Use it to override spacing, color, or size without forking the component.

<SideNav
  className="ring-2 ring-offset-2 ring-blue-500"
/>

Data attributes

Oshon components expose their internal state as data-oshon-* attributes so you can target them from CSS without coupling to internal class names. The most common attributes are listed below — see the component's source for the full set.

/* Target the secondary tier specifically */
[data-oshon-tier="secondary"] {
  --oshon-color-primary-700: var(--my-brand-color);
}

Interactive states

Every interactive component supports the standard CSS pseudo- classes plus Tailwind's state variants. Focus rings always use :focus-visible so keyboard users see them but mouse users don't.

• :hover / hover:* — pointer hover
• :focus-visible / focus-visible:* — keyboard focus
• :active / active:* — pressed
• :disabled / disabled:* — set via the disabled prop

Anatomy

The named regions a consumer composes when rendering this component. Each is documented separately so you can target keyboard nav, ARIA labels, and slot props with precision.

Keyboard

Accessibility

Every Oshon component ships axe-clean. We test in CI on every PR and publish the audit log per component.

WCAG level

2.2 AA

Screen readers tested

VoiceOver (macOS), NVDA (Windows)

Last axe audit

2026-04-22

Do / Don't

<SideNav />

const [collapsed, setCollapsed] = useState(true);
const [activeId, setActiveId] = useState('dashboard');
return (
  <SideNav
    collapsed={collapsed}
    onCollapseChange={setCollapsed}
    activeId={activeId}
    onNavigate={(item) => {
      setActiveId(item.id);
      router.push(item.href ?? '#');
    }}
  />
);

<SideNav
  items={myItems}
  branding={{
    product: { name: 'Procure', nameAccent: '360', tagline: 'Enterprise' },
    customer: { name: 'Northwind Foods', tagline: 'Est. 1892' },
    location: 'Superfood CA',
  }}
/>

<SideNav items={bigTree} maxDepth={2} />

<SideNav className="[&_[aria-current=page]]:text-blue-500" />

SideNav does NOT fetch or own routing.

<SideNav items={menuItems} />

Related

• Menu
• Dropdown
• Tabs

Design rationale

Single SideNav with a `collapsed` axis instead of two components (SideNavRail + SideNavPanel) because the two Figma states share 95% of the items tree + active-id surface — duplicating them would double the API without adding capability. Flyout + cascade are deliberately browser-hover-driven (not a controlled prop) because only the browser knows when a drag or mouseleave gesture is active; exposing them would lock callers into mirroring state they cannot observe. Panel L1 containers form a multi-open accordion (not single-open) because real navigation trees have cross-section workflows — an order-ops user jumping between Orders and Contracts should be able to keep both expanded instead of losing their place every time they toggle the other. Drill-down "Replace" is panel-only because the rail already has a deeper hover stack; reusing the panel body for drill keeps single-column mobile navigation intact (a popover cascade would overflow at <480px). The `maxDepth` prop clamps to 1–3 so a caller passing a deep tree from a CMS cannot accidentally render a 5-deep flyout chain. The native `<button>` in the tab order (not <a>) is chosen because callers own routing — href is informational metadata, not a default link target.