# Password
> Password field with a four-segment pixel strength meter, a show/hide toggle and a rule checklist; minScore blocks weak passwords.
- React: `import { PxPassword } from "@/components/lumesec/px-password"`
- Collection: Pixel UI (https://elements.lumesec.ai/components/pixel-ui)
- Registry item: https://elements.lumesec.ai/r/px-password.json
- Page: https://elements.lumesec.ai/components/pixel-ui/password



Live preview: https://elements.lumesec.ai/view/px-password

Demo source:

```tsx
import { PxPassword } from "@/components/lumesec/px-password";

export default function PxPasswordDemo() {
  return (
    <div className="w-full max-w-[400px] rounded-[14px] border border-border bg-card px-5 py-[18px] shadow-[0_14px_34px_-20px_rgb(0_0_0/0.4)]">
      <PxPassword name="password" label="New password" minScore={3} />
    </div>
  );
}
```

## Playground

Change a prop and the component re-renders. Props marked remounts set an initial value, so the component starts over.

## Installation

```bash
npx shadcn@latest add @lumesec/px-password
```

First time with the @lumesec registry? Register it once, or install by URL:

```bash
npx shadcn@latest registry add @lumesec=https://elements.lumesec.ai/r/{name}.json
npx shadcn@latest add https://elements.lumesec.ai/r/px-password.json
```

## Usage

React:

```tsx
import { PxPassword } from "@/components/lumesec/px-password";

export function Example() {
  return <PxPassword name="password" label="New password" minScore={3} />;
}
```

## Behaviour

A pixel strength meter in four segments, a show/hide toggle and a checklist whose bullets pop as each rule is met. With `minScore` set, weaker passwords block form submission.

## API reference

### Props

Also accepts every prop of `<div>` (`React.ComponentProps<"div">`), spread onto the root element.

| Prop            | Type                                              | Default      | Description                                                                                                             |
| --------------- | ------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------- |
| `value`         | `string`                                          | —            | Controlled password. Use with `onValueChange`.                                                                          |
| `defaultValue`  | `string`                                          | `""`         | Initial password when uncontrolled.                                                                                     |
| `label`         | `React.ReactNode`                                 | `"Password"` | Label above the field, linked to the input.                                                                             |
| `name`          | `string`                                          | —            | Form field name; the password submits under it.                                                                         |
| `minScore`      | `PxPasswordScore`                                 | `0`          | Lowest acceptable strength from 0 to 4 (Too weak, Weak, Fair, Good, Strong). A weaker password makes the input invalid. |
| `disabled`      | `boolean`                                         | `false`      | Dims the field and disables the input and the show/hide button.                                                         |
| `onValueChange` | `(value: string) => void`                         | —            | Called on every edit with the new password.                                                                             |
| `onScoreChange` | `(score: PxPasswordScore) => void`                | —            | Called on every edit with the strength score of the new password, 0 to 4.                                               |
| `onValueCommit` | `(value: string, score: PxPasswordScore) => void` | —            | Called when the input commits a change (on blur after editing), with the password and its score.                        |

### Ref

`ref` points at the root `HTMLDivElement`.

## Accessibility

* A native `<input type="password">` with `autocomplete="new-password"`, labelled by a `<label htmlFor>`.
* The show/hide button has `aria-pressed` and an `aria-label` that switches between "Show password" and "Hide password".
* The meter canvas has `role="meter"`, `aria-label="Password strength"`, `aria-valuemin="0"`, `aria-valuemax="4"`, `aria-valuenow` and an `aria-valuetext` with the strength word.
* The strength word is an `aria-live="polite"` region.
* The rule checklist is a plain list; met rules change colour only, without a text or ARIA state.
* A native `<input>` submits the password under `name`. When the score is below `minScore` it sets a custom validity message naming the required level, for example "Choose a stronger password (Good or better)", which blocks submission. Form reset clears the password and calls `onValueChange`.
* Reduced motion: the meter jumps to the new score, checklist bullets do not pop and the strength word swaps without rolling.

## Theming

Styled with Tailwind classes on your shadcn theme tokens, so light and dark follow your theme. The accent comes from `--lumesec`. See [Theming](/docs/theming).

This component reads `--foreground`, `--muted-foreground`, `--card`, `--border`, `--lumesec`, `--lumesec-shine`, `--destructive`, `--lumesec-warning` and `--lumesec-success`.

## Notes

* Scoring: one point each for 8 or more characters, upper and lower case, a number and a symbol. 12 or more characters with at least three of those score 4.
* Strength words and rules are in English.
* `className` and other `div` props go to the wrapper.