Zum Hauptinhalt springen
Version: latest
Universell einsetzbar

SideNav funktioniert sowohl auf dem Server als auch im Browser. Nutze immer den Standard-Import (z. B. @prokodo/ui/sidenav) — die Library erkennt die Umgebung automatisch.

SideNav

SideNav zeigt Navigationseinträge oder benannte Abschnitte als ausgeklappte Seitenleiste oder schmale Icon-Leiste. Der exportierte Name lautet SideNav, der Importpfad @prokodo/ui/sidenav.

Live demo →

Kontrollierte Navigation

Verwende collapsed mit onCollapsedChange, wenn die Anwendung, ein externer Schalter oder das responsive Layout den Zustand verwaltet. Der Callback meldet den gewünschten neuen Boolean-Wert. Die Anwendung muss ihn über collapsed zurückgeben. Mit collapsed allein bleibt die Darstellung bis zur nächsten Änderung durch die Anwendung fest.

"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"
>
Navigation umschalten
</button>
<SideNav
ariaLabel="Kontonavigation"
collapsed={collapsed}
items={items}
collapsedLabel="Menü ausklappen"
unCollapsedLabel="Menü einklappen"
onCollapsedChange={setCollapsed}
/>
</>
)
}

Unkontrollierte Navigation und Speicherung

Bestehende Anwendungen können weiterhin <SideNav items={items} initialCollapsed /> verwenden. Ohne collapsed verwaltet die Komponente ihren Zustand selbst und speichert Änderungen durch den Schalter unter localStorage["prokodo-adminSidebarCollapsed"]: "1" bedeutet eingeklappt, "0" ausgeklappt. Andere gespeicherte Werte werden ignoriert. onCollapsedChange kann auch in diesem Modus Umschaltwünsche beobachten; onChange bleibt der Callback für Navigationslinks.

Schlagen Lesen oder Schreiben fehl, bleibt die Navigation mit Zustand im Arbeitsspeicher bedienbar. Eine Speicherung über das Neuladen hinaus ist dann nicht möglich. Im kontrollierten Modus liest oder schreibt SideNav diesen Schlüssel nicht; die Anwendung entscheidet über die Speicherung. Behalte den gewählten Modus über die Lebensdauer der Komponente bei.

Serverdarstellung und mobile Einbindung

Der Server-Fallback verwendet collapsed ?? initialCollapsed ?? false und entspricht damit dem initialen Client-Zustand. Gespeicherte unkontrollierte Einstellungen werden erst nach der Hydrierung übernommen; dabei kann sich das Layout ändern. Für ein stabiles, etwa aus einem Cookie abgeleitetes Layout müssen Server und erster Client-Render denselben kontrollierten Wert erhalten. Callbacks und renderFooter benötigen die Client-Hydrierung. In Next.js gehört das zustandsbehaftete Beispiel in eine Client Component. Verwende den öffentlichen Importpfad ohne Auswahl interner /client- oder /lazy-Dateien.

Eingeklappt bedeutet eine Icon-Leiste, keinen versteckten modalen Drawer. Die Anwendung übernimmt bei mobilen Overlays Hintergrundfläche, Escape-Verhalten, Fokusbegrenzung und -rückgabe, Inertness des Hintergrunds und Scroll-Sperre. SideNav implementiert diese Funktionen und aufklappbare Untermenüs nicht.

Props

PropTypStandardBeschreibung
itemsSideNavItem[]—Flache Navigationsliste; wird verwendet, wenn sections fehlt oder leer ist.
sectionsSideNavSection[]—Nicht leere Abschnitte haben Vorrang vor items.
initialCollapsedbooleanfalseInitialer Zustand im unkontrollierten Modus. Eine gespeicherte Einstellung kann ihn nach der Hydrierung ersetzen. Bei gesetztem collapsed ohne Wirkung.
collapsedboolean—Kontrollierter Zustand. Die Anwendung übernimmt Aktualisierung und Speicherung, auch bei false.
onCollapsedChange(collapsed: boolean) => void—Meldet beim Betätigen des eingebauten Schalters den gewünschten neuen Zustand in beiden Modi. Kein Aufruf beim Mounten, Wiederherstellen einer Einstellung oder Ändern der Props durch die Anwendung.
collapsedIconIconName"ArrowRight01Icon"Schalter-Icon im eingeklappten Zustand.
unCollapsedIconIconName"ArrowLeft01Icon"Schalter-Icon im ausgeklappten Zustand.
collapsedLabelstring"Expand menu"Zugänglicher Schaltername im eingeklappten Zustand.
unCollapsedLabelstring"Collapse menu"Zugänglicher Schaltername im ausgeklappten Zustand.
iconPropsOmit<IconProps, "name">—Zusätzliche Props für das Schalter-Icon. Einträge verwenden jeweils icon.
ariaLabelstring"Main navigation"Zugänglicher Name des umgebenden <aside>.
headlinePropsOmit<HeadlineProps, "children">—Standard-Props für Abschnittsüberschriften; Abschnitts-Props haben Vorrang.
descriptionPropsOmit<HTMLAttributes<HTMLParagraphElement>, "children">—Standard-Props für Abschnittsbeschreibungen; Abschnitts-Props haben Vorrang.
renderFooter() => ReactNode—Fußbereich im ausgeklappten Zustand nach der Client-Hydrierung.
onChange(item: SideNavItem) => void—Aufruf beim Klick auf einen Navigationslink; unabhängig von Zustandsmeldungen.
classNamestring—CSS-Klasse des äußeren <aside>.

Ein Eintrag enthält label, icon als IconProps-Objekt sowie optional redirect als LinkProps und einen expliziten active-Zustand. Es gibt keinen children-Menübaum und keinen automatischen URL-Abgleich. Setze für reine Icon-Links redirect.ariaLabel und für die aktuelle Seite redirect["aria-current"] = "page"; active steuert die Gestaltung.

Ein Abschnitt enthält items sowie optional headline, description, headlineComponent, headlineProps und descriptionProps. Ein eigenes headlineComponent ersetzt den Standardblock aus Überschrift und Beschreibung. Im eingeklappten Zustand sind Abschnittsüberschriften, Beschreibungen und der Fußbereich ausgeblendet.

Siehe das vollständige SideNav-Modell.

Barrierefreiheit

Der Schalter bietet aria-expanded und aria-controls="sidenav"; sein natives Button-Verhalten unterstützt Enter und Leertaste. Übersetze die Schalternamen und benenne Links, deren sichtbarer Text beim Einklappen entfällt. Kennzeichne die aktuelle Seite explizit. Prüfe Tastaturfokus, Kontrast und Overlay-Verhalten in der Anwendung. Jest/axe und Cypress prüfen die Komponente; die vollständige WCAG-Konformität hängt auch von Einbindung und Theme ab.

Design Tokens

SideNav lässt sich über CSS Custom Properties an :root oder einem umgebenden Element anpassen.

TokenStandardwertBeschreibung
--pk-sidenav-bgvar(--pk-color-surface)Hintergrundfarbe des Seitenleisten-Panels
--pk-sidenav-shadowvar(--pk-shadow-md)Box-Shadow des Seitenleisten-Panels
--pk-sidenav-toggle-hovervar(--pk-color-surface-raised)Hintergrundfarbe des Toggle-Buttons bei Hover
--pk-sidenav-link-hover-bgcolor-mix(in srgb, var(--pk-color-brand) 10%, transparent)Hintergrundfarbe der Nav-Einträge bei Hover/Aktiv
--pk-sidenav-link-active-bgcolor-mix(in srgb, var(--pk-color-brand) 5%, transparent)Hintergrundfarbe des aktuellen Seiten-Nav-Eintrags
--pk-sidenav-icon-colorvar(--pk-color-fg)Icon-Vordergrundfarbe
--pk-sidenav-icon-bgvar(--pk-color-surface-raised)Hintergrundfarbe des Icon-Wrappers
--pk-sidenav-label-colorcolor-mix(in srgb, var(--pk-color-fg) 70%, transparent)Farbe von Collapse-Icon und -Label
--pk-sidenav-fgvar(--pk-color-fg)Hauptfarbe der Nav-Eintrags-Labels
--pk-sidenav-radiusvar(--pk-radius-sm)Border-Radius für Nav-Einträge und Icon-Wrapper
--pk-sidenav-gapvar(--pk-space-xs)Abstand zwischen den Nav-Listen-Einträgen
--pk-sidenav-link-gapvar(--pk-space-md)Interner Abstand innerhalb eines Nav-Eintrags
--pk-sidenav-section-headline-colorcolor-mix(in srgb, var(--pk-color-fg) 45%, transparent)Farbe der Abschnitts-Überschriften

Storybook

👉 SideNav in Storybook öffnen


Quellcode

src/components/sidenav/SideNav.model.ts