1. Docs
2. Formulare
3. Validierung

Validierung 1.2.0

Kombiniere CSS-Validierungszustände mit <velin-form-summary>, damit Fehler sichtbar, verlinkt und angekündigt werden - nicht nur farblich. Styles unter .velin-form--validated zielen auf natives :valid / :invalid (und :user-invalid, wo unterstützt). English: Validation

Wann verwenden

• Mehrfeld-Formulare, die nach dem Absenden eine fokussierbare Fehlerliste brauchen - ergänze <velin-form-summary>.
• Zeige Erfolgs-/Fehlerrahmen nach dem Absenden mit .velin-form--validated plus .velin-field-error / .velin-field-valid.
• Server- oder Async-Fehler: setze aria-invalid="true" und verweise mit aria-describedby auf eine Nachrichten-ID (summary verdrahtet das automatisch).

Wann nicht

• Behandle farbige Rahmen nicht als alleinige Fehlererkennung - assistive Technologien brauchen Text und aria-invalid.
• Erwarte nicht, dass initA11y() Felder validiert; rufe es nur auf, um Announcer / Focus-not-obscured-Padding zu mounten.
• Beanspruche keine AAA-Zertifizierung, nur weil Tokens AAA-orientiert sind - teste deine Flows mit realen assistiven Technologien.

So funktioniert es

Validierungsstyles sind unter .velin-form--validated gescoped. Füge diese Klasse dem <form> hinzu (typischerweise beim Absenden), um valide/ungültige Rahmen auf .velin-input, .velin-select und .velin-textarea sichtbar zu machen. Kombiniere sie mit sichtbaren Nachrichten: .velin-field-valid und .velin-field-error. Für programmatische oder Server-Fehler nutze [aria-invalid="true"] (im Core-Bundle gestylt) oder Modifier .velin-input--error / .velin-input--success.

ARIA, :user-invalid und Ehrlichkeit

Das ausgelieferte CSS stylt [aria-invalid="true"] und unter .velin-form--validated :user-invalid / :user-valid, wo der Browser sie unterstützt (vermeidet "alles rot beim Laden"). Helper umfassen .velin-field-error, .velin-field-hint und .velin-field-valid.

initA11y() setzt kein aria-invalid. Importiere aus @birdapi/velinstyle/a11y, wenn du eine gemeinsame Live-Region und Scroll Padding für fixe Navigationen möchtest:

import { initA11y } from '@birdapi/velinstyle/a11y';
initA11y({ announcer: true, scrollPadding: true });

Bevorzuge <velin-form-summary>, um beim Absenden aria-invalid und aria-describedby zu setzen. Bei eigenen Skripten setzt du beides selbst, wenn serverseitige oder asynchrone Validierung fehlschlägt.

Live-Beispiel

<form class="velin-form--validated" novalidate>
  <div class="velin-field">
    <label class="velin-label" for="name">Name</label>
    <input type="text" class="velin-input" id="name" value="Jane Doe" required>
    <div class="velin-field-valid">Looks good!</div>
  </div>

  <div class="velin-field">
    <label class="velin-label" for="email">Email</label>
    <input type="email" class="velin-input" id="email" required>
    <div class="velin-field-error">Please enter a valid email address.</div>
  </div>

  <button type="submit" class="velin-btn velin-btn--primary">Submit form</button>
</form>

JavaScript-Trigger

Füge beim Absenden .velin-form--validated hinzu, um Styles erst nach Nutzerinteraktion zu aktivieren:

document.querySelectorAll('form[novalidate]').forEach(form => {
  form.addEventListener('submit', event => {
    if (!form.checkValidity()) {
      event.preventDefault();
      event.stopPropagation();
    }
    form.classList.add('velin-form--validated');
  });
});

Serverseitige Validierung

Bei servergerenderten Fehlern wende .velin-input--success oder .velin-input--error direkt auf das Control an - kein Eltern-.velin-form--validated nötig.

<input type="text" class="velin-input velin-input--success" value="velinuser">
<div class="velin-field-valid">Username is available.</div>

<input type="password" class="velin-input velin-input--error" aria-invalid="true">
<div class="velin-field-error">Password must be at least 8 characters.</div>

Fehlerzusammenfassung (<velin-form-summary>)

Das CSS oben stylt jeweils ein Feld. In längeren Formularen brauchen Screenreader- und Tastaturnutzer zusätzlich eine zentrale Stelle, die jedes Problem benennt. <velin-form-summary> übernimmt das Absenden- Handling, baut eine fokussierbare Fehlerliste, verdrahtet aria-invalid und aria-describedby pro Feld und kündigt die Fehleranzahl über <velin-announcer> an.

Das deckt WCAG-2.2-Kriterien ab, die reines CSS nicht leisten kann: 3.3.1 Fehlererkennung, 3.3.3 Fehlerempfehlung und die aria-describedby-Hälfte von 4.1.2 Name, Rolle, Wert. Kombiniere es mit <velin-persist> für 3.3.7 Redundante Eingabe.

<form id="signup">
  <velin-form-summary heading="Please fix the following"></velin-form-summary>

  <div class="velin-field">
    <label class="velin-label" for="email">Email</label>
    <input class="velin-input" type="email" id="email" name="email" required
           data-error-message="Enter a valid email address">
  </div>

  <button class="velin-btn velin-btn--primary" type="submit">Sign up</button>
</form>

Feldtexte kommen aus data-error-message und data-error-label; ohne sie fällt das Element auf die validationMessage des Browsers und das zugehörige <label> zurück. Nutze data-error-ignore, um ein Control zu überspringen, und native-validation, um Browser-Bubbles beizubehalten. Das Element emittiert velin-form-invalid, velin-form-valid und velin-form-error-focus; validate(), clear() und focusFirstError() sind für eigene Flows verfügbar. Vollständige Referenz: Form Summary.

Barrierefreiheit

• <velin-form-summary> setzt aria-invalid, hängt Fehler-IDs an aria-describedby an und rendert eine fokussierbare role="alert"-Liste (unterstützt 3.3.1, 3.3.3 und Name/Rolle/Wert-Verdrahtung).
• Kündige Fehleranzahlen über <velin-announcer> an - initA11y({ announcer: true }) stellt eine gemeinsame Region sicher; es erfindet keine Nachrichten.
• Verlasse dich nie allein auf Farbe; halte .velin-field-error-Text neben dem Control.

Verwandt

• Form Summary — vollständige API, Events, data-error-message
• Persist — redundante Eingabe / Entwurfswerte
• Barrierefreiheit — initA11y, AAA-orientierte Standards
• Formularsteuerung · Formulare Überblick