# Password Strength

A four-step meter with a label that shows how strong a password is.

- Category: Forms
- Page: https://wunderui.com/components/password-strength
- Tier: Free

## Install

```bash
npx wunderui-cli add password-strength
```

## Import

```tsx
import { PasswordStrength, PasswordStrengthLevel } from "@/components/blocks/auth"
```

## Minimal usage

Then use it:

```tsx
import { useState } from "react"
import { Input, PasswordStrength, getPasswordStrength } from "@wunderui/react"

export function NewPassword() {
  const [password, setPassword] = useState("")
  const strength = getPasswordStrength(password) // null while empty

  return (
    <div className="flex w-full max-w-xs flex-col gap-2">
      <Input label="Password" type="password" revealable autoComplete="new-password" value={password} onChange={(event) => setPassword(event.target.value)} />
      {strength && <PasswordStrength strength={strength} />}
    </div>
  )
}
```

Expected result: You see an empty field. Type correct-horse and four-segment bars appear under it with three segments filled and the text Good password.

## Usage

```tsx
import { PasswordStrength } from "@wunderui/react"

export function Example() {
  return (
    <div className="w-full max-w-sm">
      <PasswordStrength strength="weak" />
    </div>
  )
}
```

## When to use

### Use Password Strength for

- Quick feedback under a new-password field on a sign-up, a reset or a settings form
- One overall result of how strong a password is, in four steps
- A meter with a label that a screen reader can read, next to a field the person is typing in

### Use something else

- [Password Requirement](https://wunderui.com/components/password-requirement) for rule-by-rule feedback that shows what is still missing
- [Progress](https://wunderui.com/components/progress) for the progress of a task or an upload
- [Meter](https://wunderui.com/components/meter) for a value inside a known range, such as disk use

## Behavior

What the meter renders and how it reads.

- **Display only:** PasswordStrength shows a level; it does not score a password, hold state or fire events. You pass the strength, and the segments and label change on the next render.
- **Levels:** Strength is weak, fair, good or strong, filling one to four segments and colouring segments and label red, amber, blue and green. Unfilled segments use the border colour.
- **Scoring helper:** getPasswordStrength gives one point each for 8 characters, 12 characters, mixed case, a digit and a symbol: 1 is weak, 2 fair, 3 good, 4 or 5 strong. It is a hint, not a security measure.
- **Text alternative:** The label under the bars is the text alternative: it says the level in words and is always shown, so the meter never rests on colour alone. The bars have no role, so a screen reader reads the label.
- **Announcing changes:** The wrapper is a polite live region, so a label change is spoken when the person pauses. Render the meter from the first key on and keep it mounted, or some screen readers stay silent.
- **Label:** The label replaces the default text for the level. A long text wraps under the bars, and nothing is cut.
- **Width:** The wrapper fills its parent and the four segments share the width equally. At 160 px the bars are about 37 px wide and the label still fits on one line.
- **Sample values:** Use obviously made-up passwords in examples and tests, such as correct-horse. The demos run on local state and send nothing.
- **Dark mode:** It uses theme tokens for the segments and text, so it follows the theme.
- **Motion:** None. The segments and colour change at once when the level changes; nothing fades or slides.
- **Reduced motion:** There is no motion, so reduced motion changes nothing.

## Anatomy

- `PasswordStrength`: A column with 6 px between the segments and the label, announced politely. It fills the width of its parent, holds no state and tests nothing: you pass the level.
- `Segments`: A row of four bars, 4 px high with 4 px between them, sharing the width equally. They carry no text and no role: they are drawn, not read.
- `Segment`: One bar: the first one to four are filled with the colour of the level and the rest use the border colour. Weak fills 1, fair 2, good 3, strong 4.
- `Label`: The text under the bars in 12 px type, in the colour of the level: Weak password, Fair password, Good password or Strong password, or your own label. It is always shown.

## Best practices

### Do

- Get the level from getPasswordStrength and render the meter only when it returns one (null for an empty password). Keep it mounted while the person types, so level changes are announced.
- Leave the label on: it says the level in words, so colour is never the only signal, and a screen reader reads the label, not the bars. Pass your own label for other wording or another language.
- Reserve the height of the meter and put a hint in it until the first key, as in the sign-up example, so the form does not jump when the meter appears.
- Put the meter in a column as wide as the field above it. It fills the width of its parent.

### Don't

- Don't treat the helper as your password policy: it scores only length and character kinds, so Password1! scores strong. Enforce your real rules on the server and show them with Password Requirement.
- Don't show a level for a password that is not typed. An empty field has no strength, and a weak bar for an empty field reads as an error.
- Don't use real passwords in examples, tests or screenshots; use obviously made-up strings such as correct-horse. The demos keep them in local state and send nothing.

## API reference

### PasswordStrength

| Prop | Type | Default | Description |
|---|---|---|---|
| strength* | "weak" \| "fair" \| "good" \| "strong" |  | The level to show. Required. It fills one to four segments and sets the colour. Get it from `getPasswordStrength(password)`, which returns `null` for an empty password. |
| className | string |  | Extra classes for the wrapper, merged after its own. Use them for a margin or a maximum width. |
| label | string |  | The text under the bars. Defaults to the name of the level followed by `password`. Pass your own words or another language; a long text wraps. |

## Examples

### Strength: weak, fair, good or strong

```tsx
import { PasswordStrength } from "@wunderui/react"

export function Example() {
  return (
    <div className="w-full max-w-sm">
      <PasswordStrength strength="weak" />
    </div>
  )
}
```

### Text: the default label, your own words or a long sentence

```tsx
import { PasswordStrength } from "@wunderui/react"

export function Example() {
  return (
    <div className="w-full max-w-sm">
      <PasswordStrength strength="good" />
    </div>
  )
}
```

### Scoring: the level of a password you type

```tsx
import { useState } from "react"
import { Input, PasswordStrength, getPasswordStrength } from "@wunderui/react"

export function Example() {
  const [password, setPassword] = useState("abc")
  const strength = getPasswordStrength(password) // null while the field is empty

  return (
    <div className="flex w-full max-w-xs flex-col gap-2">
      <Input label="Password" type="password" revealable autoComplete="new-password" value={password} onChange={(event) => setPassword(event.target.value)} />
      <div className="min-h-7">{strength && <PasswordStrength strength={strength} />}</div>
    </div>
  )
}
```

### Width: a meter in a column of 400, 240 or 160 px

```tsx
import { PasswordStrength } from "@wunderui/react"

export function Example() {
  return (
    <div className="w-full max-w-[400px]">
      <PasswordStrength strength="strong" />
    </div>
  )
}
```

## In context

### Sign-up: a hint under the field that turns into the meter

Until the first key, the space under the field holds a hint. The meter replaces it at the same height so the form does not move, and the password stays in this card and is never sent.

```tsx
import { useState } from "react"
import { Button, Input, PasswordStrength, getPasswordStrength } from "@wunderui/react"

export function Example() {
  const [email, setEmail] = useState("info@wunderui.com")
  const [password, setPassword] = useState("")
  const strength = getPasswordStrength(password)

  return (
    <form
      onSubmit={(event) => event.preventDefault()}
      className="flex w-full max-w-sm flex-col gap-6 rounded-xl border border-border bg-card p-6"
    >
      <h3 className="text-lg font-semibold text-foreground">Create your account</h3>
      <Input label="Work email" type="email" autoComplete="email" value={email} onChange={(event) => setEmail(event.target.value)} />
      <div className="flex flex-col gap-2">
        <Input label="Password" type="password" revealable autoComplete="new-password" value={password} onChange={(event) => setPassword(event.target.value)} />
        <div className="min-h-7">
          {strength ? <PasswordStrength strength={strength} /> : <p className="text-xs text-text-tertiary">Use 8 or more characters with letters, numbers and a symbol.</p>}
        </div>
      </div>
      <Button type="submit" variant="gradient" disabled={!email || !password}>
        Create account
      </Button>
    </form>
  )
}
```

### Change password: the product's own words, and a minimum level to save

The labels are the product's own: Too weak to use, Almost there, Good enough. Save stays off until the level is Good; the meter is only a hint, so check any rule you need on the server too.

```tsx
import { useState } from "react"
import { Button, Input, PasswordStrength, getPasswordStrength } from "@wunderui/react"

const LABELS = {
  weak: "Too weak to use",
  fair: "Almost there",
  good: "Good enough",
  strong: "Strong enough",
}

export function Example() {
  const [password, setPassword] = useState("")
  const [saved, setSaved] = useState(false)
  const strength = getPasswordStrength(password)
  const accepted = strength === "good" || strength === "strong"

  return (
    <form
      onSubmit={(event) => {
        event.preventDefault()
        setSaved(true)
      }}
      className="flex w-full max-w-sm flex-col gap-6 rounded-xl border border-border bg-card p-6"
    >
      <div className="flex flex-col gap-1">
        <h3 className="text-lg font-semibold text-foreground">Change your password</h3>
        <p className="text-sm text-text-secondary">A password has to reach Good before it can be saved.</p>
      </div>
      <div className="flex flex-col gap-2">
        <Input
          label="New password"
          type="password"
          revealable
          autoComplete="new-password"
          value={password}
          onChange={(event) => {
            setPassword(event.target.value)
            setSaved(false)
          }}
        />
        <div className="min-h-7">{strength && <PasswordStrength strength={strength} label={LABELS[strength]} />}</div>
      </div>
      <Button type="submit" variant="gradient" disabled={!accepted}>
        Save password
      </Button>
      <p role="status" className="min-h-4 text-xs text-text-success">
        {saved ? "Password saved. This is a demo: nothing was sent." : ""}
      </p>
    </form>
  )
}
```

## For AI agents

`get_component("password-strength")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
