Password Strength · Siteplane UI

Show how strong a new password is while the user types, with the requirements it still misses.

Password

Enter a password. Must contain:

At least 8 characters - Requirement not met
At least 1 number - Requirement not met
At least 1 lowercase letter - Requirement not met
At least 1 uppercase letter - Requirement not met

Pro

This example installs with a Siteplane UI Pro license key.

Get a license on the Pro page.

pnpm dlx shadcn@4.18.0 add @siteplane-pro/password-strength-demo

This Pattern is part of Siteplane UI Pro, and its source comes with a Pro license. Its previews are free to view and try.

Installation

pnpm dlx shadcn@4.18.0 add @siteplane-pro/password-strength

Pro

Installs with a Siteplane UI Pro license key. Complete the one-time Pro setup first.

Get a license on the Pro page.

Usage

import { PasswordStrength } from "@/siteplane/components/password-strength";

<PasswordStrength name="password" />;

The field rates the password against its requirements while the user types. The level follows the share of requirements met. It is weak while at most half are met, medium above half and strong when all are met. The meter takes the destructive, warning and success tone in that order, and an empty field reads “Enter a password”. Pass value and onValueChange to control the password, or defaultValue to leave it uncontrolled. labels replaces the words of the pattern, such as the level names, for an application in another language.

Composition

PasswordStrength
├── Field
│   ├── FieldLabel
│   └── InputGroup
│       ├── InputGroupInput (the password)
│       └── InputGroupAddon
│           └── Button profile="field-action" (show or hide)
├── Meter (in the tone of the level)
├── status line (describes the input)
└── requirement list
    └── requirement: a check or an X, then its label

Each part is a Siteplane UI component, so the field, the show and hide action and the meter keep their states, focus ring and motion. A met requirement draws its check in; one that is no longer met draws it back out.

Floating label

labelPlacement="floating" draws the label inside the field, where it stands in for the placeholder until the field has focus or a value, as a floating label field does. The meter, the status line and the requirements stay below the field.

Create account

Pro

This example installs with a Siteplane UI Pro license key.

Get a license on the Pro page.

pnpm dlx shadcn@4.18.0 add @siteplane-pro/password-strength-floating-label-example

Custom requirements

requirements replaces the four default requirements. Each one has an id, a label and a test that receives the password and returns whether it is met. The list shows them in order, and the levels scale to their number. To add to the defaults, spread defaultPasswordRequirements into your list.

<PasswordStrength
  requirements={[
    {
      id: "length",
      label: "At least 12 characters",
      test: (value) => value.length >= 12,
    },
    {
      id: "spaces",
      label: "No spaces",
      test: (value) => value.length > 0 && !/\s/.test(value),
    },
  ]}
/>

Password

Medium password. Must contain:

At least 12 characters - Requirement met
At least 1 symbol - Requirement met
No spaces - Requirement not met

Pro

This example installs with a Siteplane UI Pro license key.

Get a license on the Pro page.

pnpm dlx shadcn@4.18.0 add @siteplane-pro/password-strength-custom-requirements-example

API reference

Component properties
Prop	Type	Default	Description
`label`	`ReactNode`	`Password`	The visible label of the field.
`labels`	`Partial<PasswordStrengthLabels>`	`English`	Replaces words of the pattern and keeps the English default for the others. The keys are listed below.
`labelPlacement`	`top \| floating`	`top`	Draws the label above the field, or inside it, where it floats up on focus or once there is a value.
`requiredIndicator`	`boolean`	`false`	Marks the label with the Field's red asterisk while the input is required.
`requirements`	`PasswordRequirement[]`	`defaultPasswordRequirements`	What the password is rated against, listed in order: each with an id, a label and a test(value).
`value`	`string`	`unset`	The controlled password.
`defaultValue`	`string`	`empty`	The initial password when uncontrolled. A form reset restores it.
`onValueChange`	`(value: string) => void`	`unset`	Called with the password on every change.
`disabled`	`boolean`	`false`	Disables the field and its show and hide action.
`name`	`string`	`unset`	Name of the password in the form data.
`autoComplete`	`string`	`new-password`	Lets password managers suggest a new password.
`variant`	`default \| elevated \| inset \| soft`	`default`	Surface of the field that holds the input and its show and hide action.
`className`	`string`	`unset`	Layout of the root, such as its width.
`getPasswordStrength(value, requirements?)`	`PasswordStrengthResult`	`requirements: the four defaults`	Rates a password without rendering: the met flag of each requirement, the score, the total and the level (none, weak, medium or strong).

PasswordStrengthProps extends the Input props without type, onChange, profile and unstyled. value, defaultValue, onValueChange, className and variant work as the table describes, and the remaining props, such as id, required, aria-* and ref, reach the input. The module also exports defaultPasswordRequirements, passwordStrengthLabels (the English level names) and the types PasswordRequirement, PasswordStrengthLabels, PasswordStrengthLevel and PasswordStrengthResult.

Labels

Each key of labels replaces one English word or phrase. The level names are also the text of the announcement and the value that the meter reads out. The requirements bring their own label, so pass requirements to translate them.

Component properties
Prop	Type	Default	Description
`none / weak / medium / strong`	`string`	`Enter a password / Weak password / Medium password / Strong password`	The level names in the status line, the announcement and the meter's value.
`mustContain`	`string`	`Must contain:`	Ends the status line before the requirement list.
`requirements`	`string`	`Password requirements`	Accessible name of the requirement list.
`met / notMet`	`string`	`Requirement met / Requirement not met`	Read after each requirement, so screen readers hear whether it is met.
`show / hide`	`string`	`Show password / Hide password`	Accessible name of the show and hide action.
`strength`	`string`	`Password strength`	Accessible name of the meter.

Usage notes

The strength is guidance for the user. It counts the requirements met and does not judge how guessable a password is, so validate the password on the server as well.

Keep the requirements visible while the user types, so they can see what is still missing. Use the Pattern where a password is chosen, such as sign-up and password change; a sign-in field needs no requirements.

The show and hide action keeps the field-action contract: an icon-only Button inside the field, named “Show password” or “Hide password”, that reports whether it is pressed. The status line describes the input, and the meter reads the level as its value. Each requirement tells screen readers whether it is met.

A polite live region announces the level once it has stayed the same for half a second, so the announcement does not interrupt typing. It stays silent on the first render, because the field describes itself when it takes focus.