PasswordField
A labelled password box with a button that shows or hides what's typed, and optional requirements.
import { PasswordField } from "@butteryui/react";Demo
When to use it
Use it for
- Signing in, with the saved password filled in (the default)
- Choosing a password, with autoComplete="new-password" and the rules it has to meet
- A PIN in a dense panel, with size="sm"; on a card, with variant="soft"
Not for
- Codes sent by email or text: use OneTimeCodeField, or AuthFlow for a whole passwordless sign-in
Examples
Change password
An account's password section: the current password, a new one with its rules, and Change password, held back until both are ready.
New password
A new password kept in state, its rules ticked off as it's typed, and Save held back until they're all met.
- At least 8 characters
- A number
Not saved yet
Refund password
A refund password that's disabled until the shop asks for one, with an error under it when it's too short to save.
Sign in password
The password on a sign-in form, filled in by the browser's saved password and read from the form when it's sent.
Two sizes
A soft md password among an app's settings, and an lg one, 48px with 16px text, for a sign-in page.
Staff read it out to customers who ask.
Variants and states
Show and hide
The eye button shows what's typed; it's a toggle with one name, "Show password".
That password doesn't match this email.
Requirements
Rules listed under the field, each ticked once it's met.
- At least 8 characters
- A number
- Not your email address
Sizes, outline and soft
28, 34 and 48px tall; in a small box the reveal button draws at the badge height and keeps a 28px target. Soft sits on bg-control, its edge showing on hover and focus.
Props
PasswordField
| Prop | Type | Default | Description |
|---|---|---|---|
revealLabel | string | "Show password" | What the button that shows the password is called. Defaults to "Show password". |
requirements | readonly PasswordRequirement[] | Rules the password has to meet, listed under the field with a tick beside each one it meets. | |
metLabel | string | "Met" | What a met rule is called for screen readers. Defaults to "Met". |
unmetLabel | string | "Not met" | What a rule not met yet is called for screen readers. Defaults to "Not met". |
labelrequired | string | What the field asks for, shown above it. | |
hint | ReactNode | A hint under the label, such as the format expected. | |
error | ReactNode | What's wrong, shown under the field and read with it. Leave it out while nothing is. | |
value | string | The text. Pair with onValueChange or onChange to control it. | |
defaultValue | string | The starting text when uncontrolled. | |
onValueChange | ((value: string) => void) | Called with the text on every change. | |
size | TextFieldSize | "md" | "md" (34px, 30 compact, the default), "sm" (28px) for a toolbar or a dense panel, or "lg" (48px, 40
compact, with 16px text) for sign-in pages. |
variant | "outline" | "soft" | "outline" | "outline" (the default), a 1px control-border edge on bg-surface, or "soft", a bg-control fill whose
edge shows only on hover and while it has focus, for a field on a card or in a toolbar. |
iconStart | ComponentType<IconComponentProps> | An icon at the start of the box, such as Mail from lucide-react. Decorative. | |
announceError | boolean | true | Whether a new error is read out as it appears. Defaults to true; turn it off when an error summary
that takes focus reads the errors instead. |
It also takes Omit<ComponentPropsWithRef<"input">, "size" | "value" | "defaultValue" | "children" | "type">.
PasswordRequirement
One rule a password has to meet, and whether it does yet.
| Field | Type | Default | Description |
|---|---|---|---|
labelrequired | string | The rule, such as "At least 8 characters". | |
metrequired | boolean | Whether the password meets it now. |
Accessibility
The reveal button is a toggle with a fixed name ("Show password") and aria-pressed, in the tab order after the input. Requirements are a list that describes the input; each rule has a tick named "Met" or a circle named "Not met", so its state doesn't rest on color. A shown password is never corrected, capitalized or spell-checked, and hides again when its form is submitted.
| Keys | What they do |
|---|---|
| Tab | Moves from the password box to the button that shows the password |
| Enter or Space | Shows or hides the password, from that button |
| Enter | Sends its form from the password box, and a shown password hides again |
Motion
It doesn't move.
With reduced motion: Nothing changes.
Layout
It fills its container. Its box is 34px tall (--bt-h-control) at size="md", the default, 28px (--bt-h-sm) at "sm" and 48px (--bt-h-cta) with 16px text at "lg", with the 28px reveal button inside its end; in a small box the button draws at the badge height and keeps its 28px target. A soft box keeps its edge transparent until hover or focus. The label, with its hint 6px under it, sits 8px above the box, and the error and the requirements follow 8px apart under it, the rules 6px from one another; all of them wrap.
Related
See it in the roastery demo's settings.