Skip to content

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-Nutzung
  • mmm-checkbox-group: Wrapper für mehrere Checkboxen mit gemeinsamer Value-Verwaltung

Inputs mmm-checkbox

InputTypBeschreibung
labelstring | undefinedSichtbares Label der Checkbox
supportingTextstring | undefinedZusätzlicher Hilfetext unter dem Label
errorMessagestring | undefinedFehlermeldung im Error-State
ariaLabelstring | undefinedAlternativer Screenreader-Text
namestringName des nativen Inputs im Standalone-Modus
valueunknownWert der Checkbox innerhalb einer Group (Standard: true)
disabledbooleanDeaktiviert die Checkbox
readonlybooleanZeigt den Zustand an, verhindert aber Änderungen
requiredbooleanMarkiert den nativen Input als erforderlich
hiddenbooleanBlendet die Checkbox aus
errorbooleanAktiviert den Error-State manuell
indeterminatebooleanZeigt den Indeterminate-State an; ein Klick hebt ihn auf. Unterstützt [(indeterminate)]
checkedbooleanChecked-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

OutputTypBeschreibung
checkedChangebooleanNeuer Checked-State im Standalone-Modus. Feuert auch bei programmatischen Änderungen, z. B. beim Formular-Reset
indeterminateChangebooleanFeuert, wenn ein Klick den Indeterminate-State aufhebt
changeCustomEvent<{ checked: boolean; value: unknown }>Nur bei Benutzerinteraktion: geänderter Zustand inklusive Value
touchvoidDie Checkbox wurde umgeschaltet oder verlassen (nur Standalone-Modus)

Inputs mmm-checkbox-group

InputTypBeschreibung
valueT[]Ausgewählte Werte. Unterstützt [(value)]
legendstring | undefinedBeschriftung des fieldset
headlinestring | undefinedZusätzliche Überschrift innerhalb der Gruppe
supportingTextstring | undefinedGruppentext unterhalb der Optionen
errorMessagestring | undefinedFehlermeldung der Gruppe
disabledbooleanDeaktiviert die gesamte Gruppe
readonlybooleanZeigt die Auswahl an, verhindert aber Änderungen
hiddenbooleanBlendet die Gruppe aus
errorbooleanAktiviert den Error-State der Gruppe manuell
requiredbooleanKennzeichnet die Gruppe als erforderlich (Sternchen an der legend)
minLengthnumber | undefinedMindestanzahl ausgewählter Optionen. Ab 1 erscheint ebenfalls das Sternchen; geprüft wird die Regel vom Formular
namestringName, 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

OutputTypBeschreibung
valueChangeT[]Aktuelle Auswahl als Array. Feuert auch bei programmatischen Änderungen, z. B. beim Formular-Reset
changeCustomEvent<{ value: T[] }>Nur bei Benutzerinteraktion: aktuelle Auswahl als CustomEvent
touchvoidEine 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. minLength ab 1 blendet das Sternchen ebenfalls ein.
  • Der Typ der Werte richtet sich nach dem Feld: value="mail" für ein string[], [value]="1" für ein number[]. Verglichen wird mit Object.is, "1" und 1 sind also verschiedene Werte.
  • Fehlermeldungen erscheinen, sobald das Feld touched ist. 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, required und name kommen 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-group implementiert ControlValueAccessor für Mehrfachauswahl-Arrays (formControlName, [(ngModel)]).
  • mmm-checkbox implementiert ControlValueAccessor fü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

  • checked ist nur im Standalone-Modus relevant. In einer Group wird der Zustand über value und den Group-Value gesteuert.
  • Fehlertexte haben Vorrang: zuerst errorMessage, dann die Fehlermeldungen aus dem Schema. Ohne Fehlertext wird supportingText angezeigt, im Error-State in Fehlerdarstellung.
  • In einer Gruppe zeigt die Gruppe die Fehlermeldung an. Die einzelnen Checkboxen werden nur rot markiert, ihr eigener supportingText bleibt neutral.
  • readonly stellt die Checkboxen wie deaktiviert dar, sie bleiben aber fokussierbar.
  • Für Gruppen sollte legend gesetzt werden, damit die Auswahl semantisch korrekt beschrieben ist.

Beispiele

<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>
Benachrichtigungskanäle
Wähle die gewünschten Kanäle
Mehrfachauswahl ist möglich.