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.
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
| Prop | Typ | Standard | Beschreibung |
|---|---|---|---|
items | SideNavItem[] | — | Flache Navigationsliste; wird verwendet, wenn sections fehlt oder leer ist. |
sections | SideNavSection[] | — | Nicht leere Abschnitte haben Vorrang vor items. |
initialCollapsed | boolean | false | Initialer Zustand im unkontrollierten Modus. Eine gespeicherte Einstellung kann ihn nach der Hydrierung ersetzen. Bei gesetztem collapsed ohne Wirkung. |
collapsed | boolean | — | 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. |
collapsedIcon | IconName | "ArrowRight01Icon" | Schalter-Icon im eingeklappten Zustand. |
unCollapsedIcon | IconName | "ArrowLeft01Icon" | Schalter-Icon im ausgeklappten Zustand. |
collapsedLabel | string | "Expand menu" | Zugänglicher Schaltername im eingeklappten Zustand. |
unCollapsedLabel | string | "Collapse menu" | Zugänglicher Schaltername im ausgeklappten Zustand. |
iconProps | Omit<IconProps, "name"> | — | Zusätzliche Props für das Schalter-Icon. Einträge verwenden jeweils icon. |
ariaLabel | string | "Main navigation" | Zugänglicher Name des umgebenden <aside>. |
headlineProps | Omit<HeadlineProps, "children"> | — | Standard-Props für Abschnittsüberschriften; Abschnitts-Props haben Vorrang. |
descriptionProps | Omit<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. |
className | string | — | 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.
| Token | Standardwert | Beschreibung |
|---|---|---|
--pk-sidenav-bg | var(--pk-color-surface) | Hintergrundfarbe des Seitenleisten-Panels |
--pk-sidenav-shadow | var(--pk-shadow-md) | Box-Shadow des Seitenleisten-Panels |
--pk-sidenav-toggle-hover | var(--pk-color-surface-raised) | Hintergrundfarbe des Toggle-Buttons bei Hover |
--pk-sidenav-link-hover-bg | color-mix(in srgb, var(--pk-color-brand) 10%, transparent) | Hintergrundfarbe der Nav-Einträge bei Hover/Aktiv |
--pk-sidenav-link-active-bg | color-mix(in srgb, var(--pk-color-brand) 5%, transparent) | Hintergrundfarbe des aktuellen Seiten-Nav-Eintrags |
--pk-sidenav-icon-color | var(--pk-color-fg) | Icon-Vordergrundfarbe |
--pk-sidenav-icon-bg | var(--pk-color-surface-raised) | Hintergrundfarbe des Icon-Wrappers |
--pk-sidenav-label-color | color-mix(in srgb, var(--pk-color-fg) 70%, transparent) | Farbe von Collapse-Icon und -Label |
--pk-sidenav-fg | var(--pk-color-fg) | Hauptfarbe der Nav-Eintrags-Labels |
--pk-sidenav-radius | var(--pk-radius-sm) | Border-Radius für Nav-Einträge und Icon-Wrapper |
--pk-sidenav-gap | var(--pk-space-xs) | Abstand zwischen den Nav-Listen-Einträgen |
--pk-sidenav-link-gap | var(--pk-space-md) | Interner Abstand innerhalb eines Nav-Eintrags |
--pk-sidenav-section-headline-color | color-mix(in srgb, var(--pk-color-fg) 45%, transparent) | Farbe der Abschnitts-Überschriften |