Zum Inhalt springen
Dokumentation

Komponenten

Kontrollkästchen (Checkbox)

Stabil

Mehrere unabhängige Optionen auswählen – mit gesperrtem und gemischtem Zustand.

Ein Kontrollkästchen schaltet eine einzelne Option ein oder aus. Mehrere Kästchen nebeneinander erlauben eine Mehrfachauswahl, etwa die Aufgaben einer Übergabe.

Wann verwenden

  • Für Mehrfachauswahl: jede Option gilt für sich, mehrere dürfen gewählt sein.
  • Für eine Bestätigung, die Teil eines Formulars ist und erst beim Absenden gilt – etwa „Datenschutzhinweis bestätigt“.
  • Für eine übergeordnete Auswahl „Alle“ mit gemischtem Zustand, wenn nur ein Teil der Zeilen gewählt ist.

Wann nicht

  • Für eine Auswahl, bei der genau ein Wert gelten darf, nimm eine Optionsgruppe.
  • Für eine Einstellung, die sofort wirkt, ist ein Schalter die klarere Form.
  • Für eine Aktion, die ausgeführt wird, gehört eine Schaltfläche hin.

Mehrfachauswahl

Der gemischte Zustand indeterminate zeigt an, dass nur ein Teil der Unterpunkte gewählt ist. Sobald du oben umschaltest, springen alle Unterpunkte mit.

Beispiel und Quelltext
auswahl.tsx
import * as React from "react";

import { Checkbox, Label } from "@neodin-eu/ui";

const aufgaben = [
  { id: "visite", label: "Visite vorbereiten" },
  { id: "kurve", label: "Kurve prüfen" },
  { id: "uebergabe", label: "Übergabe notieren" },
];

function Auswahl() {
  const [alle, setAlle] = React.useState<boolean | "indeterminate">("indeterminate");
  const [erledigt, setErledigt] = React.useState<string[]>([]);

  const toggleAlle = (next: boolean | "indeterminate") => {
    setAlle(next);
    setErledigt(next === true ? aufgaben.map((aufgabe) => aufgabe.id) : []);
  };

  const toggle = (id: string, next: boolean | "indeterminate") => {
    const updated =
      next === true ? [...erledigt, id] : erledigt.filter((eintrag) => eintrag !== id);
    setErledigt(updated);
    setAlle(
      updated.length === 0 ? false : updated.length === aufgaben.length ? true : "indeterminate",
    );
  };

  return (
    <div className="flex w-full max-w-sm flex-col gap-3">
      <div className="flex items-center gap-2">
        <Checkbox id="alle-aufgaben" checked={alle} onCheckedChange={toggleAlle} />
        <Label htmlFor="alle-aufgaben">Alle Aufgaben</Label>
      </div>
      <div className="ml-6 flex flex-col gap-2">
        {aufgaben.map(({ id, label }) => (
          <div key={id} className="flex items-center gap-2">
            <Checkbox
              id={id}
              checked={erledigt.includes(id)}
              onCheckedChange={(next) => toggle(id, next)}
            />
            <Label htmlFor={id}>{label}</Label>
          </div>
        ))}
      </div>
    </div>
  );
}

Zustände

Neben „an“ und „aus“ gibt es den gemischten Zustand und den gesperrten Zustand. Ein gesperrtes Kästchen bleibt sichtbar und behält seine Beschriftung.

Beispiel und Quelltext
zustaende.tsx
import { Checkbox, Label } from "@neodin-eu/ui";

function Zustaende() {
  return (
    <div className="flex flex-col gap-3">
      <div className="flex items-center gap-2">
        <Checkbox id="rueckruf" defaultChecked />
        <Label htmlFor="rueckruf">Rückruf erlaubt</Label>
      </div>
      <div className="flex items-center gap-2">
        <Checkbox id="datenschutz" />
        <Label htmlFor="datenschutz">Datenschutzhinweis bestätigt</Label>
      </div>
      <div className="flex items-center gap-2">
        <Checkbox id="teilweise" defaultChecked="indeterminate" />
        <Label htmlFor="teilweise">Einige Nachweise fehlen</Label>
      </div>
      <div className="flex items-center gap-2">
        <Checkbox id="gesperrt" disabled />
        <Label htmlFor="gesperrt">Vom Administrator gesperrt</Label>
      </div>
    </div>
  );
}

Barrierefreiheit

  • Checkbox rendert über Radix ein Element mit der Rolle checkbox. aria-checked steht auf "true", "false" oder "mixed" – der gemischte Zustand ist im Komponententest abgesichert.
  • Tab fokussiert das Kästchen, die Leertaste schaltet es um und meldet den neuen Zustand über onCheckedChange. Beides ist im Komponententest abgesichert.
  • Ein gesperrtes Kästchen nimmt keinen Klick an und ändert seinen Zustand nicht.
  • Die sichtbare Beschriftung kommt über Label und id und ist der zugängliche Name. Die Komponente ist in hell und dunkel frei von axe-Verstößen.

Props

Props von Checkbox
PropTypStandardPflichtBeschreibung
asChildboolean–Nein–
classNamestring–Nein–
disabledboolean–Nein–

Siehe auch