Zum Inhalt springen
Dokumentation

Komponenten

Farbschema (ThemeProvider, ThemeToggle)

Stabil

Hell, dunkel oder wie das System: das Farbschema hängt an einer Klasse am Wurzelelement und wird über semantische Tokens wirksam.

Das Farbschema hängt an der Klasse dark auf dem <html>-Element. Setzt sie, wechseln alle semantischen Tokens – Flächen, Text, Ränder, Statusfarben – und die Komponenten folgen ohne eigene Fallunterscheidung. ThemeProvider setzt die Klasse, ThemeToggle schaltet zwischen hell, dunkel und System.

Wann verwenden

  • Immer, einmal pro Anwendung: ThemeProvider gehört ins Root-Layout.
  • ThemeToggle in der Kopfzeile, damit Nutzer die Darstellung selbst wählen – im Nachtdienst ist dunkel oft angenehmer, am Empfang hell.
  • Die Option „System“ als Standard lassen: Sie folgt der Einstellung des Betriebssystems, ohne dass jemand etwas einstellen muss.

Wann nicht

  • Kein zweiter ThemeProvider in einer Unterseite. Die Klasse sitzt am Dokument, ein zweiter Provider würde dagegen arbeiten.
  • Kein eigenes Umschalten mit useTheme an mehreren Stellen; ein ThemeToggle pro Kopfzeile reicht.
  • Nicht für einen einzelnen Bereich innerhalb einer Seite. Das Farbschema gilt für das ganze Dokument; für abgesetzte Flächen gibt es Karten und Hinweise.

Einrichten

ThemeProvider kommt ins Root-Layout (app/layout.tsx), innerhalb von <body>. suppressHydrationWarning auf <html> ist nötig, weil die Theme-Klasse vor der Hydration gesetzt wird:

tsx
import "@neodin-eu/ui/styles.css";
import { NeodinProvider, ThemeProvider } from "@neodin-eu/ui";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="de" suppressHydrationWarning>
      <body>
        <ThemeProvider>
          <NeodinProvider locale="de-AT">{children}</NeodinProvider>
        </ThemeProvider>
      </body>
    </html>
  );
}

Der Provider setzt attribute="class", defaultTheme="system", enableSystem und disableTransitionOnChange – der Wechsel blendet also nicht jede Farbe einzeln über. useTheme kommt aus diesem Paket weiterhin von next-themes und liefert theme, resolvedTheme und setTheme.

Umschalten

ThemeToggle ist ein Knopf mit dem Symbol des aktuellen Schemas; sein zugänglicher Name ist die aktuelle Einstellung („Hell“, „Dunkel“ oder „System“). Das Menü bietet die drei Möglichkeiten mit Symbol und Text an.

Darstellung

Hell, dunkel oder wie das System.

Beispiel und Quelltext
umschalten.tsx
import { ThemeToggle } from "@neodin-eu/ui";

function Umschalten() {
  return (
    <div className="flex w-full max-w-md items-center justify-between gap-4 rounded-md border border-border bg-background p-4">
      <div className="flex flex-col gap-1">
        <p className="text-sm font-semibold text-foreground">Darstellung</p>
        <p className="text-sm text-muted-foreground">Hell, dunkel oder wie das System.</p>
      </div>
      <ThemeToggle />
    </div>
  );
}

ThemeToggle braucht den Provider: Ohne ihn hat useTheme kein Ziel und der Wechsel bleibt wirkungslos.

Barrierefreiheit

  • Der Knopf ist ein Button mit aria-label der aktuellen Einstellung; das Menü ist ein DropdownMenu von Radix. Die Einträge haben die Rolle menuitemradio – der Komponententest findet sie über getByRole("menuitemradio", { name: "Hell" }) und ebenso „Dunkel“ und „System“.
  • Die Auswahl von „Dunkel“ setzt die Klasse dark auf documentElement; das prüft der Komponententest mit waitFor.
  • Tastatur nach Radix-Verhalten: Enter oder Leertaste öffnet das Menü, die Pfeiltasten bewegen den Fokus, Enter übernimmt den Eintrag, Esc schließt ohne Änderung.
  • Die Auswahl ist als Radiogruppe ausgezeichnet; Screenreader lesen die aktuelle Einstellung mit vor. Am Dokument selbst ändert sich für Screenreader nichts – nur Farben wechseln.

Props

Props von ThemeProvider
PropTypStandardPflichtBeschreibung
valueValueObject–NeinMapping of theme name to HTML attribute value. Object where key is the theme name and value is the attribute value

Die Tabelle enthält nur value; alle weiteren Props kommen von next-themes (defaultTheme, enableSystem, forcedTheme …) und stehen deshalb nicht darin. Die vier Grundeinstellungen setzt die Bibliothek bereits.

Props von ThemeToggle
PropTypStandardPflichtBeschreibung
classNamestring–NeinAdditional classes for the trigger button.

Siehe auch