# Password Requirement

One password rule in a checklist that turns green once the password meets it.

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

## Install

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

## Import

```tsx
import { PasswordRequirement } from "@/components/blocks/auth"
```

## Minimal usage

Then use it:

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

export function Rules({ password }: { password: string }) {
  const long = password.length >= 8
  return (
    <ul aria-label="Password requirements" className="flex flex-col gap-1.5">
      <PasswordRequirement met={long}>
        At least 8 characters
        <span className="sr-only">{long ? ", met" : ", not met"}</span>
      </PasswordRequirement>
    </ul>
  )
}
```

Expected result: You see a grey circle with the text At least 8 characters. Pass a password of eight or more characters and the circle turns into a green check.

## Usage

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

export function Example() {
  return (
    <ul aria-label="Password requirements" className="mx-auto flex w-fit max-w-xs flex-col gap-1.5">
      <PasswordRequirement met={false}>
        At least 8 characters
        <span className="sr-only">, not met</span>
      </PasswordRequirement>
      <PasswordRequirement met={false}>
        At least one number
        <span className="sr-only">, not met</span>
      </PasswordRequirement>
      <PasswordRequirement met={false}>
        Upper and lower case letters
        <span className="sr-only">, not met</span>
      </PasswordRequirement>
      <PasswordRequirement met={false}>
        At least one symbol
        <span className="sr-only">, not met</span>
      </PasswordRequirement>
    </ul>
  )
}
```

## When to use

### Use Password Requirement for

- The rules of a new password on a sign-up or a reset form, checked as the person types
- Any short list of conditions that a typed value has to meet, such as a username or a workspace address
- A list that must stay visible next to the field, so the person sees what is missing before they submit

### Use something else

- [Password Strength](https://wunderui.com/components/password-strength) for one overall result of how strong a password is, as a meter and a word
- [Alert](https://wunderui.com/components/alert) for an error after a submit, written as a sentence with what to do
- [Checkbox](https://wunderui.com/components/checkbox) for a list that people tick themselves

## Behavior

What the component renders and what it leaves to the page.

- **Display only:** PasswordRequirement shows a result; it does not test a password, hold state or fire events. You compute met from the value and pass it, and the row changes on the next render.
- **States:** When met is true the icon is a green check in a circle and the label uses the secondary colour. When false the icon is an empty circle and the label is tertiary.
- **Semantics:** The row is an li, so the list counts the rules. The icon is hidden and the component adds no state text, so a screen reader reads the label only, unless you add a hidden met or not met.
- **Announcing changes:** A row that changes colour is not announced. Put a status line with the count of met rules near the list: it is spoken when the number changes, not on every key press.
- **Not focusable:** The row is not interactive: no focus, no hover state, not a tab stop. The field it describes is the control.
- **Long labels:** The label wraps and is never cut, and the icon is centred on the whole label, so on two lines it sits between them. Align items to the start in the class to keep it beside the first line.
- **Sample values:** Use obviously made-up passwords in examples and tests, such as correct-horse-battery. The demos run on local state and send nothing.
- **Dark mode:** It uses the theme tokens for the text and the success colour, so it follows the theme.
- **Motion:** None. The icon and the colour change at once when met changes; nothing fades or moves.
- **Reduced motion:** There is no motion, so reduced motion changes nothing.

## Anatomy

- `PasswordRequirement`: An li in a 12 px flex row with 8 px between icon and label, carrying a met data attribute when the rule is met. It renders no list, so put it inside a ul or ol.
- `Icon`: A 16 px Lucide icon: a check in a circle in the success colour when the rule is met, an empty circle when it is not. It is hidden from assistive technology.
- `Label`: The rule text, in the secondary colour when met and the tertiary colour when not. Add a visually hidden word for the state, such as met, so a screen reader reads it.

## Best practices

### Do

- Put the requirements in a ul with an aria-label such as Password requirements. The component is an li, and a list tells a screen reader how many rules there are.
- Add a hidden word after the label for the state, such as met or not met, in a screen-reader-only span. Without it the state is shown by icon and colour only, which a screen reader does not read.
- Run every rule on each change and pass the result as met. Keep the rules in one array, so the list and the check that enables the submit button never disagree.
- Say the total in a status line next to the list, such as 3 of 4 requirements met. It changes only when the count does, so a screen reader announces progress without reading the list on every key.
- Point the password field at the list with aria-describedby, so the rules are read when the field gets focus.

### Don't

- Don't rely on the green icon alone to show a result, since people who cannot see colour miss it and the unmet circle is not an error. Keep the text and the hidden state word.
- Don't show an unmet rule as an error before the person has typed. An empty field with every circle empty is the starting point, not a failure.
- Don't use it for a checklist of tasks: it is a rule that a value passes or fails. Use Checklist Task for steps someone completes.

## API reference

### PasswordRequirement

| Prop | Type | Default | Description |
|---|---|---|---|
| children* | ReactNode |  | The label of the rule, as text or any content. Add a visually hidden word for the state after it so a screen reader hears whether the rule is met. |
| met* | boolean |  | Whether the password meets the rule. Required. `true` shows the green check, the secondary text colour and `data-met`; `false` shows the empty circle and the tertiary colour. |
| className | string |  | Extra classes for the row, merged after its own. Use them for `items-start` on a label that wraps or a different text size. |

## Examples

### State: a rule that is met or not met yet

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

export function Example() {
  return (
    <ul aria-label="Password requirements" className="mx-auto flex w-fit max-w-xs flex-col gap-1.5">
      <PasswordRequirement met={false}>
        At least 8 characters
        <span className="sr-only">, not met</span>
      </PasswordRequirement>
    </ul>
  )
}
```

### Content: a short label, a long label or a long label aligned to the top

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

export function Example() {
  return (
    <ul aria-label="Password requirements" className="mx-auto flex w-fit max-w-xs flex-col gap-1.5">
      <PasswordRequirement met={false}>
        At least 8 characters
        <span className="sr-only">, not met</span>
      </PasswordRequirement>
    </ul>
  )
}
```

### Rules: a basic and a strict set run on the password you type

```tsx
import { useId, useState } from "react"
import { Input, PasswordRequirement } from "@wunderui/react"

const RULES = [
  { id: "length", label: "At least 8 characters", test: (value: string) => value.length >= 8 },
  { id: "number", label: "At least one number", test: (value: string) => /[0-9]/.test(value) },
  { id: "case", label: "Upper and lower case letters", test: (value: string) => /[a-z]/.test(value) && /[A-Z]/.test(value) },
]

export function Example() {
  const listId = useId()
  const [password, setPassword] = useState("correct-horse")
  const results = RULES.map((rule) => ({ ...rule, met: rule.test(password) }))
  const metCount = results.filter((rule) => rule.met).length

  return (
    <div className="flex w-full max-w-xs flex-col gap-3">
      <Input
        label="New password"
        type="password"
        revealable
        autoComplete="new-password"
        aria-describedby={listId}
        value={password}
        onChange={(event) => setPassword(event.target.value)}
      />
      <ul id={listId} aria-label="Password requirements" className="flex flex-col gap-1.5">
        {results.map((rule) => (
          <PasswordRequirement key={rule.id} met={rule.met}>
            {rule.label}
            <span className="sr-only">{rule.met ? ", met" : ", not met"}</span>
          </PasswordRequirement>
        ))}
      </ul>
      <p role="status" className="text-xs text-text-secondary">
        {metCount} of {RULES.length} requirements met
      </p>
    </div>
  )
}
```

## In context

### Sign-up: a password field with live rules and a strength meter

The rules and the meter follow every key press. A counter says how many rules are met and the account button stays off until all are; the password stays in this card and is never sent.

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

const RULES = [
  { id: "length", label: "At least 8 characters", test: (value: string) => value.length >= 8 },
  { id: "case", label: "Upper and lower case letters", test: (value: string) => /[a-z]/.test(value) && /[A-Z]/.test(value) },
  { id: "number", label: "At least one number", test: (value: string) => /[0-9]/.test(value) },
  { id: "symbol", label: "At least one symbol", test: (value: string) => /[^A-Za-z0-9]/.test(value) },
]

export function Example() {
  const listId = useId()
  const [email, setEmail] = useState("info@wunderui.com")
  const [password, setPassword] = useState("")
  const [created, setCreated] = useState(false)
  const results = RULES.map((rule) => ({ ...rule, met: rule.test(password) }))
  const metCount = results.filter((rule) => rule.met).length
  const strength = getPasswordStrength(password)

  return (
    <form
      onSubmit={(event) => {
        event.preventDefault()
        setCreated(true)
      }}
      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-3">
        <Input
          label="Password"
          type="password"
          revealable
          autoComplete="new-password"
          aria-describedby={listId}
          value={password}
          onChange={(event) => {
            setPassword(event.target.value)
            setCreated(false)
          }}
        />
        {strength && <PasswordStrength strength={strength} />}
        <ul id={listId} aria-label="Password requirements" className="flex flex-col gap-1.5">
          {results.map((rule) => (
            <PasswordRequirement key={rule.id} met={rule.met}>
              {rule.label}
              <span className="sr-only">{rule.met ? ", met" : ", not met"}</span>
            </PasswordRequirement>
          ))}
        </ul>
        <p role="status" className="text-xs text-text-secondary">
          {metCount} of {RULES.length} requirements met
        </p>
      </div>
      <Button type="submit" variant="gradient" disabled={metCount < RULES.length}>
        Create account
      </Button>
      <p role="status" className="min-h-4 text-xs text-text-success">
        {created ? "Account created for " + email + ". This is a demo: nothing was sent." : ""}
      </p>
    </form>
  )
}
```

### Set a new password: rules that depend on other fields

Two rules look at another field: the new password must differ from the current one and match the confirmation. Try the demo's current password, then fix it.

```tsx
import { useId, useState } from "react"
import { Button, Input, PasswordRequirement } from "@wunderui/react"

const CURRENT = "demo-old-password"

export function Example() {
  const listId = useId()
  const [password, setPassword] = useState("")
  const [confirm, setConfirm] = useState("")
  const [saved, setSaved] = useState(false)

  const results = [
    { id: "length", label: "At least 12 characters", met: password.length >= 12 },
    { id: "number", label: "At least one number", met: /[0-9]/.test(password) },
    { id: "new", label: "Different from your current password", met: password.length > 0 && password !== CURRENT },
    { id: "match", label: "Matches the confirmation", met: password.length > 0 && password === confirm },
  ]
  const metCount = results.filter((rule) => rule.met).length

  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">Set a new password</h3>
        <p className="text-sm text-text-secondary">In this demo your current password is {CURRENT}.</p>
      </div>
      <Input
        label="New password"
        type="password"
        revealable
        autoComplete="new-password"
        aria-describedby={listId}
        value={password}
        onChange={(event) => {
          setPassword(event.target.value)
          setSaved(false)
        }}
      />
      <Input
        label="Confirm new password"
        type="password"
        revealable
        autoComplete="new-password"
        value={confirm}
        onChange={(event) => {
          setConfirm(event.target.value)
          setSaved(false)
        }}
      />
      <div className="flex flex-col gap-3">
        <ul id={listId} aria-label="Password requirements" className="flex flex-col gap-1.5">
          {results.map((rule) => (
            <PasswordRequirement key={rule.id} met={rule.met}>
              {rule.label}
              <span className="sr-only">{rule.met ? ", met" : ", not met"}</span>
            </PasswordRequirement>
          ))}
        </ul>
        <p role="status" className="text-xs text-text-secondary">
          {metCount} of {results.length} requirements met
        </p>
      </div>
      <Button type="submit" variant="gradient" disabled={metCount < results.length}>
        Update password
      </Button>
      <p role="status" className="min-h-4 text-xs text-text-success">
        {saved ? "Password updated. This is a demo: nothing was saved." : ""}
      </p>
    </form>
  )
}
```

## For AI agents

`get_component("password-requirement")`

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