Checkbox
Überblick
mmm-checkbox bildet einzelne Auswahloptionen mit Label, Supporting Text, Error-State und Indeterminate-State ab. Für Mehrfachauswahlen steht zusätzlich mmm-checkbox-group als gruppierender Wrapper mit gemeinsamer Beschriftung und Fehlermeldung zur Verfügung. Beide Komponenten funktionieren mit Signal Forms ([formField]) ebenso wie mit Reactive und Template-driven Forms.
Subkomponenten
mmm-checkbox: einzelne Checkbox für Standalone- oder Gruppen-Nutzungmmm-checkbox-group: Wrapper für mehrere Checkboxen mit gemeinsamer Value-Verwaltung
Inputs mmm-checkbox
| Input | Typ | Beschreibung |
|---|---|---|
label | string | undefined | Sichtbares Label der Checkbox |
supportingText | string | undefined | Zusätzlicher Hilfetext unter dem Label |
errorMessage | string | undefined | Fehlermeldung im Error-State |
ariaLabel | string | undefined | Alternativer Screenreader-Text |
name | string | Name des nativen Inputs im Standalone-Modus |
value | unknown | Wert der Checkbox innerhalb einer Group (Standard: true) |
disabled | boolean | Deaktiviert die Checkbox |
readonly | boolean | Zeigt den Zustand an, verhindert aber Änderungen |
required | boolean | Markiert den nativen Input als erforderlich |
hidden | boolean | Blendet die Checkbox aus |
error | boolean | Aktiviert den Error-State manuell |
indeterminate | boolean | Zeigt den Indeterminate-State an; ein Klick hebt ihn auf. Unterstützt [(indeterminate)] |
checked | boolean | Checked-State im Standalone-Modus. Unterstützt [(checked)] |
Mit [formField] setzt Signal Forms außerdem die Formularzustände touched, invalid, errors und disabledReasons.
Outputs mmm-checkbox
| Output | Typ | Beschreibung |
|---|---|---|
checkedChange | boolean | Neuer Checked-State im Standalone-Modus. Feuert auch bei programmatischen Änderungen, z. B. beim Formular-Reset |
indeterminateChange | boolean | Feuert, wenn ein Klick den Indeterminate-State aufhebt |
change | CustomEvent<{ checked: boolean; value: unknown }> | Nur bei Benutzerinteraktion: geänderter Zustand inklusive Value |
touch | void | Die Checkbox wurde umgeschaltet oder verlassen (nur Standalone-Modus) |
Inputs mmm-checkbox-group
| Input | Typ | Beschreibung |
|---|---|---|
value | T[] | Ausgewählte Werte. Unterstützt [(value)] |
legend | string | undefined | Beschriftung des fieldset |
headline | string | undefined | Zusätzliche Überschrift innerhalb der Gruppe |
supportingText | string | undefined | Gruppentext unterhalb der Optionen |
errorMessage | string | undefined | Fehlermeldung der Gruppe |
disabled | boolean | Deaktiviert die gesamte Gruppe |
readonly | boolean | Zeigt die Auswahl an, verhindert aber Änderungen |
hidden | boolean | Blendet die Gruppe aus |
error | boolean | Aktiviert den Error-State der Gruppe manuell |
required | boolean | Kennzeichnet die Gruppe als erforderlich (Sternchen an der legend) |
minLength | number | undefined | Mindestanzahl ausgewählter Optionen. Ab 1 erscheint ebenfalls das Sternchen; geprüft wird die Regel vom Formular |
name | string | Name, der an enthaltene Checkboxen weitergegeben wird |
Mit [formField] setzt Signal Forms außerdem die Formularzustände touched, invalid, errors und disabledReasons.
Outputs mmm-checkbox-group
| Output | Typ | Beschreibung |
|---|---|---|
valueChange | T[] | Aktuelle Auswahl als Array. Feuert auch bei programmatischen Änderungen, z. B. beim Formular-Reset |
change | CustomEvent<{ value: T[] }> | Nur bei Benutzerinteraktion: aktuelle Auswahl als CustomEvent |
touch | void | Eine Option wurde umgeschaltet oder der Fokus hat die Gruppe verlassen |
Forms und Verhalten
Signal Forms
Das Formular wird an die Gruppe gebunden, nie an die einzelnen Checkboxen einer Gruppe. Der Wert ist ein Array mit den values der ausgewählten Checkboxen, in der Reihenfolge, in der sie angehakt wurden. Eine einzelne Checkbox ohne Gruppe bindet ein boolean-Feld.
import { FormField, form, minLength, required } from '@angular/forms/signals';
readonly model = signal({ channels: ['push'] as string[], acceptsTerms: false });
readonly f = form(this.model, (path) => { minLength(path.channels, 1, { message: 'Bitte wähle mindestens einen Kanal aus.' }); required(path.acceptsTerms, { message: 'Bitte akzeptiere die AGB.' });});<mmm-checkbox-group legend="Benachrichtigungskanäle" [formField]="f.channels"> <mmm-checkbox value="mail" label="E-Mail"></mmm-checkbox> <mmm-checkbox value="push" label="Push"></mmm-checkbox> <mmm-checkbox value="sms" label="SMS"></mmm-checkbox></mmm-checkbox-group>
<mmm-checkbox label="Ich akzeptiere die AGB" [formField]="f.acceptsTerms"></mmm-checkbox>- Mindestens eine Auswahl:
minLength(path.x, 1, { message }).required()schlägt bei Arrays nie fehl, weil Signal Forms ein leeres Array nicht als leer wertet – es blendet nur das Sternchen ein.minLengthab1blendet das Sternchen ebenfalls ein. - Der Typ der Werte richtet sich nach dem Feld:
value="mail"für einstring[],[value]="1"für einnumber[]. Verglichen wird mitObject.is,"1"und1sind also verschiedene Werte. - Fehlermeldungen erscheinen, sobald das Feld
touchedist. Die Gruppe gilt als berührt, wenn eine Option umgeschaltet wird oder der Fokus die Gruppe verlässt – nicht schon beim Wechsel zwischen ihren Checkboxen. disabled,readonly,hidden,requiredundnamekommen aus dem Schema. Neben[formField]dürfen sie weder gebunden noch als Attribut gesetzt werden; Angular meldet das als Compile-Fehler.
Reactive und Template-driven Forms
mmm-checkbox-groupimplementiertControlValueAccessorfür Mehrfachauswahl-Arrays (formControlName,[(ngModel)]).mmm-checkboximplementiertControlValueAccessorfür boolesche Standalone-Nutzung.- Innerhalb einer Group wird der Checked-State einzelner Checkboxen aus dem Group-Value abgeleitet.
SCSS-Variablen
Wichtige Variablen für mmm-checkbox:
--mmm-checkbox-size--mmm-checkbox-gap--mmm-checkbox-border-color--mmm-checkbox-background--mmm-checkbox-active-color--mmm-checkbox-error-color--mmm-checkbox-disabled-border--mmm-checkbox-disabled-background
Wichtige Variablen für mmm-checkbox-group:
--mmm-checkbox-group-gap--mmm-checkbox-group-items-gap--mmm-checkbox-group-legend-gap--mmm-checkbox-group-headline-gap--mmm-checkbox-group-message-gap--mmm-checkbox-group-error-color
Hinweise
checkedist nur im Standalone-Modus relevant. In einer Group wird der Zustand übervalueund den Group-Value gesteuert.- Fehlertexte haben Vorrang: zuerst
errorMessage, dann die Fehlermeldungen aus dem Schema. Ohne Fehlertext wirdsupportingTextangezeigt, im Error-State in Fehlerdarstellung. - In einer Gruppe zeigt die Gruppe die Fehlermeldung an. Die einzelnen Checkboxen werden nur rot markiert, ihr eigener
supportingTextbleibt neutral. readonlystellt die Checkboxen wie deaktiviert dar, sie bleiben aber fokussierbar.- Für Gruppen sollte
legendgesetzt werden, damit die Auswahl semantisch korrekt beschrieben ist.
Beispiele
<div style="display:grid; gap: 1rem;">
<mmm-checkbox
label="Newsletter abonnieren"
supportingText="Du kannst dich jederzeit wieder abmelden."
></mmm-checkbox>
<mmm-checkbox
label="AGB akzeptieren"
[checked]="true"
></mmm-checkbox>
<mmm-checkbox
label="Teilweise ausgewählt"
[indeterminate]="true"
></mmm-checkbox>
<mmm-checkbox
label="Pflichtfeld"
[error]="true"
errorMessage="Bitte triff eine Auswahl."
></mmm-checkbox>
<mmm-checkbox
label="Nicht verfügbar"
supportingText="Diese Option ist aktuell deaktiviert."
[disabled]="true"
></mmm-checkbox>
</div>
<mmm-checkbox-group
legend="Benachrichtigungskanäle"
headline="Wähle die gewünschten Kanäle"
supportingText="Mehrfachauswahl ist möglich."
name="features"
[(ngModel)]="selectedValues"
[error]="hasError"
errorMessage="Bitte wähle mindestens einen Kanal aus."
>
<mmm-checkbox value="mail" label="E-Mail"></mmm-checkbox>
<mmm-checkbox value="push" label="Push"></mmm-checkbox>
<mmm-checkbox value="sms" label="SMS"></mmm-checkbox>
</mmm-checkbox-group>