InputPassword
Synonyme: Passwort-Eingabefeld, Passwortfeld, Password Input, Password Field
Beschreibung: Mit InputPassword können Passwörter eingegeben und bearbeitet werden.
Die Komponente basiert auf dem nativen HTML5-Eingabetyp password und unterstützt Funktionen wie das Ein- und Ausblenden des Passworts sowie die Konfiguration der maximalen Eingabelänge.
Beispiel
Standard-Passwortfeld mit Beschriftung und optional aktivierter Sichtbarkeitsfunktion:
<KolInputPassword _label="Passwort" _variant="default" _visibilityToggle={true} />Barrierefreiheit
- Das Eingabefeld muss mit einer aussagekräftigen Beschriftung (
_label) versehen werden. - Zusätzliche Hinweise können über
_hint, Fehlermeldungen über_msgbereitgestellt werden. - Die Sichtbarkeitsfunktion (
_visibilityToggle) wird als eigenständiger Button umgesetzt und ist vollständig über Tastatur sowie assistive Technologien bedienbar. - Über
_iconseingebundene Icons sind rein dekorativ und werden vor assistiven Technologien verborgen (aria-hidden).
Konkrete Designentscheidungen
| Entscheidung | Begründung |
|---|---|
Verwendung des nativen HTML5-Eingabetyps password | Die Komponente nutzt bewusst den nativen HTML5-Eingabetyp password und profitiert dadurch von dessen standardisierter Unterstützung durch Browser und assistive Technologien. |
| Aktualisierung des Zeichenzählers | Bei aktiviertem Zeichenzähler (_has-counter) wird dieser mit einer Verzögerung von 1000 ms aktualisiert, um Screenreader nicht bei jeder Eingabe zu unterbrechen. Ist kein Zeichenzähler aktiv, aber _max-length gesetzt, wird stattdessen ein versteckter, nur für assistive Technologien sichtbarer Hinweis bereitgestellt. |
| Fokusmanagement | Die Basis-Komponente setzt den nativen Fokusring zurück. Der sichtbare Fokusindikator wird durch das jeweils verwendete Theme bereitgestellt. |
Links und Referenzen
Verwendung
- Nutzen Sie
_visibilityToggle, um das Passwort bei Bedarf ein- und ausblenden zu können. - Verwenden Sie
_max-length, um die maximal zulässige Anzahl an Zeichen zu begrenzen. - Nutzen Sie
_max-length-behavior, um festzulegen, ob die Zeichenbegrenzung nativ durchgesetzt oder lediglich angezeigt wird. - Setzen Sie
_autoCompletepassend zum Anwendungsfall, beispielsweise aufcurrent-passwordfür Anmeldungen odernew-passwordfür die Vergabe neuer Passwörter.
Hinweis: Die Komponente setzt _autoComplete standardmäßig auf "off". Überschreiben Sie diesen Wert in produktiven Formularen in der Regel explizit, damit Browser und Passwort-Manager das Eingabefeld korrekt erkennen und unterstützen können.
Tastatursteuerung
Die Tastaturbedienung wird durch den Browser und das Betriebssystem bestimmt. Daher können sich einzelne Tastaturfunktionen je nach Browser, Betriebssystem und Endgerät unterscheiden.
Typischerweise werden folgende Funktionen unterstützt:
| Taste | Funktion |
|---|---|
Tab | Fokus auf das Eingabefeld bzw. das nächste fokussierbare Element setzen. |
Shift+Tab | Fokus auf das vorherige fokussierbare Element setzen. |
Pfeiltasten | Cursor innerhalb des Eingabefelds bewegen. |
Pos1 / Ende | Cursor an den Anfang bzw. das Ende des Eingabewerts setzen. |
Hinweis: Ist _visibilityToggle aktiviert, kann der Sichtbarkeits-Button über Tab fokussiert und mit Enter oder Leertaste betätigt werden.
Best Practices / Empfehlungen
- Setzen Sie
_autoCompletepassend zum Anwendungsfall ein. Verwenden Siecurrent-passwordfür Anmeldungen undnew-passwordfür die Vergabe neuer Passwörter, damit Browser und Passwort-Manager das Eingabefeld korrekt erkennen und unterstützen können. - Nutzen Sie
_visibilityToggle, wenn Nutzende ihre Passworteingabe vor dem Absenden überprüfen können sollen. Berücksichtigen Sie dabei, ob das Anzeigen des Passworts in der jeweiligen Nutzungssituation angemessen ist. - Begrenzen Sie die Passwortlänge bei Bedarf über
_max-lengthund wählen Sie mit_max-length-behaviordas zum Anwendungsfall passende Verhalten. - Formulieren Sie Passwortanforderungen und Validierungsfehler verständlich und stellen Sie diese über
_hintbzw._msgbereit. - Verwenden Sie
_placeholderausschließlich als zusätzliche Orientierung und nicht als Ersatz für eine aussagekräftige Beschriftung (_label).
Anwendungsfälle
- Eingabe eines Passworts bei der Anmeldung an einer Anwendung
- Vergabe eines neuen Passworts bei der Registrierung eines Benutzerkontos
- Festlegen oder Ändern eines Passworts in den Kontoeinstellungen
- Bestätigung eines neuen Passworts in Registrierungs- oder Änderungsformularen
- Eingabe eines Passworts zur Authentifizierung besonders geschützter Aktionen
FAQ
Wann sollte ich _visibilityToggle verwenden?
Nutzen Sie _visibilityToggle, wenn Nutzende ihre Passworteingabe vor dem Absenden überprüfen können sollen, beispielsweise bei der Vergabe komplexer Passwörter. Berücksichtigen Sie dabei, ob das Anzeigen des Passworts in der jeweiligen Nutzungssituation angemessen ist.
Wie kann ich die Länge eines Passworts begrenzen?
Mit _has-counter, _max-length und _max-length-behavior können Sie eine Längenbegrenzung mit Zeichenzähler konfigurieren. _max-length-behavior="hard" verhindert die Eingabe nach Erreichen der festgelegten Zeichenanzahl, während "soft" weitere Eingaben zulässt und die verbleibenden Zeichen im Zähler negativ dargestellt werden.
Wie sollte _autoComplete verwendet werden?
Verwenden Sie current-password für Anmeldungen und new-password für die Vergabe neuer Passwörter. Dadurch können Browser und Passwort-Manager das Eingabefeld korrekt erkennen und unterstützen.
Kann ich zusätzliche Passwortregeln prüfen?
Ja. Nutzen Sie beispielsweise _pattern oder eine anwendungsspezifische Validierung, um zusätzliche Anforderungen wie Mindestlänge, Sonderzeichen oder bestimmte Passwortregeln umzusetzen.
Konstruktion / Technik
Playground
Testen Sie die verschiedenen Eigenschaften des Passwortfelds:
<KolInputPassword _label="Passwort" _visibilityToggle={true} />Funktionalitäten (mit Code)
Basis-Passwortfeld
Standard-Passwortfeld mit Beschriftung:
<KolInputPassword _label="Passwort" _visibilityToggle={false} />Sichtbarkeitsfunktion (Auge-Icon)
Passwortfeld mit Toggle zum Anzeigen/Verbergen des Passworts:
<KolInputPassword _label="Passwort" _visibilityToggle={true} />Formular-Attribute
Standardattribute für Formulare (Pflichtfeld, deaktiviert, read-only, etc.):
<KolInputPassword _label="Passwort" _visibilityToggle={true} />Hinweise und Fehlermeldungen
Hilfetext und Validierungsmeldungen:
<KolInputPassword _hint="Mindestens 8 Zeichen erforderlich" _label="Passwort" _visibilityToggle={true} />Zeichenzähler und Längenbegrenzung
Passwortfeld mit Zeichenzähler und Längenbegrenzung (hart oder weich):
<KolInputPassword _hasCounter={true} _label="Passwort" _maxLength={20} _visibilityToggle={true} />Events und Eingabeverarbeitung
Das InputPassword unterstützt verschiedene Events für die Eingabeverarbeitung:
| Event | Auslöser | Value |
|---|---|---|
click | Passwortfeld wird angeklickt | — |
focus | Passwortfeld wird fokussiert | — |
blur | Passwortfeld verliert Fokus | — |
input | Wert wird durch Eingabe geändert | Aktueller Wert des Passwortfelds |
change | Eingabe wurde abgeschlossen | Aktueller Wert des Passwortfelds |
Zur Behandlung von Events bzw. Callbacks siehe
API
Overview
The Password input type creates an input field for passwords. The input is masked with dot symbols.
Properties
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
_accessKey | _access-key | Defines the key combination that can be used to trigger or focus the component's interactive element. | string | undefined | undefined |
_autoComplete | _auto-complete | Defines whether the input can be auto-completed. | string | undefined | 'off' |
_disabled | _disabled | Makes the element not focusable and ignore all events. | boolean | undefined | false |
_hasCounter | _has-counter | Shows a character counter for the input element. | boolean | undefined | false |
_hideLabel | _hide-label | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | boolean | undefined | false |
_hideMsg | _hide-msg | Hides the error message but leaves it in the DOM for the input's aria-describedby. | boolean | undefined | false |
_hint | _hint | Defines the hint text. | string | undefined | '' |
_icons | _icons | Defines the icon classnames (e.g. _icons="fa-solid fa-user"). | string | undefined | { right?: IconOrIconClass | undefined; left?: IconOrIconClass | undefined; } | undefined |
_label (required) | _label | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to false to enable the expert slot. | string | undefined |
_maxLength | _max-length | Defines the maximum number of input characters. | number | undefined | undefined |
_maxLengthBehavior | _max-length-behavior | Defines the behavior when maxLength is set. 'hard' sets the maxlength attribute, 'soft' shows a character counter without preventing input. | "hard" | "soft" | undefined | 'hard' |
_msg | _msg | Defines the properties for a message rendered as Alert component. | Omit<AlertProps, "_on" | "_label" | "_level" | "_variant" | "_hasCloser"> & { _description: string; } | string | undefined | undefined |
_name | _name | Defines the technical name of an input field. | string | undefined | undefined |
_on | -- | Gibt die EventCallback-Funktionen für das Input-Event an. | InputTypeOnBlur & InputTypeOnClick & InputTypeOnChange & InputTypeOnFocus & InputTypeOnInput & InputTypeOnKeyDown | undefined | undefined |
_pattern | _pattern | Defines a validation pattern for the input field. | string | undefined | undefined |
_placeholder | _placeholder | Defines the placeholder for input field. To be shown when there's no value. | string | undefined | undefined |
_readOnly | _read-only | Makes the input element read only. | boolean | undefined | false |
_required | _required | Makes the input element required. | boolean | undefined | false |
_shortKey | _short-key | Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud. | string | undefined | undefined |
_smartButton | _smart-button | Allows to add a button with an arbitrary action within the element (_hide-label only). | string | undefined | { _label: string; } & { _type?: "button" | "reset" | "submit" | undefined; _accessKey?: string | undefined; _on?: ButtonCallbacksPropType<StencilUnknown> | undefined; _ariaExpanded?: boolean | undefined; _tabIndex?: number | undefined; _value?: StencilUnknown; _role?: "tab" | "treeitem" | undefined; _ariaControls?: string | undefined; _ariaDescription?: string | undefined; _ariaSelected?: boolean | undefined; _customClass?: string | undefined; _disabled?: boolean | undefined; _hideLabel?: boolean | undefined; _icons?: IconsPropType | undefined; _id?: string | undefined; _inline?: boolean | undefined; _name?: string | undefined; _shortKey?: string | undefined; _syncValueBySelector?: string | undefined; _tooltipAlign?: AlignPropType | undefined; _variant?: string | undefined; } | undefined |
_tooltipAlign | _tooltip-align | Defines where to show the Tooltip preferably: top, right, bottom or left. | "bottom" | "left" | "right" | "top" | undefined | 'top' |
_touched | _touched | Shows if the input was touched by a user. | boolean | undefined | false |
_value | _value | Defines the value of the element. | string | undefined | undefined |
_variant | _variant | Defines which variant should be used for presentation. | string | undefined | undefined |
_visibilityToggle | _visibility-toggle | Activates the show password button | boolean | undefined | false |
Methods
click
click() => Promise<void>
Clicks the primary interactive element inside this component.
Returns
Type: Promise<void>
focus() => Promise<void>
Sets focus on the internal element.
Returns
Type: Promise<void>
getValue() => Promise<string | undefined>
Returns the current value.
Returns
Type: Promise<string | undefined>
Slots
| Slot | Description |
|---|---|
| The label of the input field. |