# Password Strength

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

Password field with a strength meter and its requirements

**Pro** — This example installs with a Siteplane UI Pro license key. Get a license on the [Pro page](/pricing).

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

This Pattern is part of [Siteplane UI Pro](/pricing), and its source comes with a [Pro license](/docs/license/#patterns). Its previews are free to view and try.

## Installation

**Pro** — Installs with a Siteplane UI Pro license key. Complete the one-time [Pro setup](/docs/installation/#siteplane-ui-pro) first. Get a license on the [Pro page](/pricing).

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

With npm: `npx shadcn@4.18.0 add @siteplane-pro/password-strength`.

## Usage

```tsx
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

```text
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](/docs/components/field/#floating-label) does. The meter, the status line and the requirements stay below the field.

Create account card with floating labels

**Pro** — This example installs with a Siteplane UI Pro license key. Get a license on the [Pro page](/pricing).

```bash
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.

```tsx
<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),
    },
  ]}
/>
```

Three custom requirements

**Pro** — This example installs with a Siteplane UI Pro license key. Get a license on the [Pro page](/pricing).

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

## API reference

| 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.

| 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.