Input Password
A password input with a built-in visibility toggle. Clicking the eye icon switches between masked and plain-text views.
Keyboard interaction
| Key | Action |
|---|---|
| Tab | Move focus to the input or the show/hide toggle button (if visible). |
| Shift + Tab | Move focus to the previous focusable element. |
| Type | Enter text directly into the password field. |
| Enter | Submit the enclosing form (if any). |
Screen reader behaviour
The following ARIA attributes are managed internally by the component:
| Property | Value | Note |
|---|---|---|
aria-label (toggle button) | Switches between "Show password" / "Hide password" | Dynamically updated so screen readers announce the current toggle state. |
aria-required | "true" when required is set | Communicates the required state to assistive technologies. |
aria-invalid | "true" when state="error" | Signals a validation failure. Paired with aria-describedby pointing at the error message. |
aria-describedby | ID of the message or description element | Links the error or description text to the input so screen readers announce it on focus. |
aria-label / aria-labelledby | From label prop | Associates the visible label with the inner input regardless of its current type (password or text). |
Label association
The label is associated with the inner <input type="password"> or <input type="text"> (when revealed) via Shadow DOM id association. Screen readers announce the label on focus in both states.
Visibility toggle button
When showToggle is true, an icon button is rendered inside the field. Its aria-label dynamically changes between "Show password" and "Hide password" to reflect current state. It is keyboard focusable with a visible focus ring applied by getFocusStyle.
Toggling switches the inner input type between password and text. Screen readers re-announce the field contents when the type switches to text — inform users via the accessible description if this is a concern.
Required fields
required adds a visual asterisk and aria-required="true".
Validation state
state="error" sets aria-invalid="true" and links the error message via aria-describedby.
Focus management
delegatesFocus: true routes host focus to the inner input. Reduced-motion styles respect prefers-reduced-motion.
WCAG 2.2 compliance
1.3.1 Info and Relationships — APass
Label, required indicator, and error message are all programmatically associated with the input via ARIA attributes.
1.4.3 Contrast (Minimum) — AAPass
Input text and label foreground colours meet the 4.5:1 minimum contrast ratio against the field background in both themes.
2.1.1 Keyboard — APass
All functionality is operable via keyboard, including the show/hide toggle button.
2.4.7 Focus Visible — AAPass
A visible focus ring is applied on keyboard focus using :focus-visible styles.
3.3.1 Error Identification — APass
When state="error", the error message is linked via aria-describedby so screen readers announce it on focus.
4.1.2 Name, Role, Value — APass
The inner <input> exposes correct name, role, and value; the toggle button has an accessible aria-label at all times.
Best practices
- Reduced motion — all CSS transitions inside the shadow DOM respond to
prefers-reduced-motion: reduceand are suppressed automatically. - Visibility re-announcement — toggling the input type from
passwordtotextcauses screen readers to re-announce the field value. Inform users via a description if revealing the password is a concern in your context. - Error messaging — always pair
state="error"with a meaningfulmessageprop. Colour alone is insufficient for users who cannot distinguish red from other colours.