Skip to main content
Version: latest
Works everywhere

SideNav works in both server and client environments. Always use the standard import (e.g. @prokodo/ui/sidenav) — the library detects the runtime automatically.

SideNav

SideNav renders navigation items or named sections as an expanded sidebar or an icon-only rail. Use the exported SideNav name and @prokodo/ui/sidenav import.

Live demo →

Controlled navigation

Use collapsed with onCollapsedChange when an application shell, external button or responsive layout owns the state. The callback requests the next boolean; the parent must pass that value back to update the sidebar. Providing only collapsed makes the displayed state fixed until the parent changes it.

"use client"

import { useState } from "react"
import { SideNav, type SideNavProps } from "@prokodo/ui/sidenav"
import "@prokodo/ui/sidenav.css"

const items: SideNavProps["items"] = [
{
label: "Dashboard",
icon: { name: "Home01Icon" },
active: true,
redirect: {
href: "/dashboard",
ariaLabel: "Dashboard",
"aria-current": "page",
},
},
{
label: "Settings",
icon: { name: "Settings01Icon" },
redirect: { href: "/settings", ariaLabel: "Settings" },
},
]

export function AppNavigation() {
const [collapsed, setCollapsed] = useState(false)

return (
<>
<button
style={{ minHeight: 44, minWidth: 44 }}
aria-controls="sidenav"
aria-expanded={!collapsed}
onClick={() => setCollapsed(value => !value)}
type="button"
>
Toggle navigation
</button>
<SideNav
ariaLabel="Account navigation"
collapsed={collapsed}
items={items}
onCollapsedChange={setCollapsed}
/>
</>
)
}

Uncontrolled navigation and storage

Existing consumers can continue to use <SideNav items={items} initialCollapsed />. Without collapsed, the component manages its own state and stores toggle changes under localStorage["prokodo-adminSidebarCollapsed"]: "1" means collapsed and "0" expanded. Other stored values are ignored. onCollapsedChange can also observe toggle requests in this mode; onChange remains the navigation-link callback.

If reading or writing storage throws, navigation still works with in-memory state. Persistence across reloads is then unavailable. In controlled mode SideNav never reads or writes that key: the parent decides whether and how to persist. Choose one mode for the component's lifetime.

Server rendering and mobile integration

The server fallback uses collapsed ?? initialCollapsed ?? false, matching the initial client state. Stored uncontrolled preferences are applied only after hydration, so the initial layout can change then. For a stable layout derived from a cookie, pass the same controlled value on server and initial client render. Callbacks and renderFooter require client hydration. In Next.js, the stateful example belongs in a Client Component; use the standard public import, without selecting internal /client or /lazy files.

Collapsed means an icon rail, not a hidden modal drawer. A mobile overlay belongs to the application shell, including its backdrop, Escape handling, focus trap and return, background inertness and scroll lock. SideNav does not implement those behaviors or collapsible submenus.

Props

PropTypeDefaultDescription
itemsSideNavItem[]—Flat navigation items; used when sections is absent or empty.
sectionsSideNavSection[]—Non-empty sections take precedence over items.
initialCollapsedbooleanfalseInitial uncontrolled state. A stored preference may replace it after hydration. Ignored while collapsed is provided.
collapsedboolean—Controlled state. The parent owns updates and persistence, including when the value is false.
onCollapsedChange(collapsed: boolean) => void—Reports the requested next state when the built-in toggle is activated, in either mode. It is not called on mount, stored preference restoration or parent prop updates.
collapsedIconIconName"ArrowRight01Icon"Toggle icon while collapsed.
unCollapsedIconIconName"ArrowLeft01Icon"Toggle icon while expanded.
collapsedLabelstring"Expand menu"Accessible toggle label while collapsed.
unCollapsedLabelstring"Collapse menu"Accessible toggle label while expanded.
iconPropsOmit<IconProps, "name">—Additional props for the toggle icon. Item icons use each item's icon.
ariaLabelstring"Main navigation"Accessible label on the wrapping <aside>.
headlinePropsOmit<HeadlineProps, "children">—Default section heading props; section-level props take precedence.
descriptionPropsOmit<HTMLAttributes<HTMLParagraphElement>, "children">—Default section description props; section-level props take precedence.
renderFooter() => ReactNode—Footer shown while expanded after client hydration.
onChange(item: SideNavItem) => void—Called when a navigation link is clicked; separate from collapse notifications.
classNamestring—CSS class on the root <aside>.

Each item supplies label, icon (an IconProps object), an optional redirect (LinkProps) and an explicit active state. There is no children menu tree or automatic URL matching. Set redirect.ariaLabel for icon-only links and redirect["aria-current"] = "page" for the current page; active controls styling.

A section supplies items plus optional headline, description, headlineComponent, headlineProps and descriptionProps. A custom headlineComponent replaces the standard heading/description block. Section headings, descriptions and the footer are hidden while collapsed.

See the complete SideNav model.

Accessibility

The toggle exposes aria-expanded and aria-controls="sidenav"; its native button supports Enter and Space. Supply localized toggle labels and accessible names for links that remain after their visible text is collapsed. Mark the current page explicitly. Verify keyboard focus, contrast and overlay behavior in the final application. Jest/axe and Cypress checks cover the component; complete WCAG conformance also depends on the integration and theme.

Design Tokens

Customise SideNav via CSS custom properties on :root or a scoped ancestor.

TokenDefaultDescription
--pk-sidenav-bgvar(--pk-color-surface)Background color of the sidebar panel
--pk-sidenav-shadowvar(--pk-shadow-md)Box-shadow of the sidebar panel
--pk-sidenav-toggle-hovervar(--pk-color-surface-raised)Background color of the toggle button on hover
--pk-sidenav-link-hover-bgcolor-mix(in srgb, var(--pk-color-brand) 10%, transparent)Background color of nav items on hover/active
--pk-sidenav-link-active-bgcolor-mix(in srgb, var(--pk-color-brand) 5%, transparent)Background color of the current page nav item
--pk-sidenav-icon-colorvar(--pk-color-fg)Icon foreground color
--pk-sidenav-icon-bgvar(--pk-color-surface-raised)Icon wrapper background color
--pk-sidenav-label-colorcolor-mix(in srgb, var(--pk-color-fg) 70%, transparent)Collapse icon and label color
--pk-sidenav-fgvar(--pk-color-fg)Main nav item label color
--pk-sidenav-radiusvar(--pk-radius-sm)Border-radius for nav items and icon wrappers
--pk-sidenav-gapvar(--pk-space-xs)Gap between nav list items
--pk-sidenav-link-gapvar(--pk-space-md)Internal gap inside each nav item
--pk-sidenav-section-headline-colorcolor-mix(in srgb, var(--pk-color-fg) 45%, transparent)Color of section headline labels

Storybook

👉 Open SideNav in Storybook


Source

src/components/sidenav/SideNav.model.ts