# PasswordInput

> Password entry with a show/hide toggle and an optional strength meter.

Category: Forms · Status: stable · Package: @bindshq/stance-react@0.1.1 · Docs: https://stanceui.com/components/password-input

Use PasswordInput for sign-in and password creation. The visibility toggle lets people check what they typed, which reduces errors more than a confirm-password field. Enable strength on sign-up and password change; supply your own scorer to match your password policy.

## Import

```tsx
import { PasswordInput, estimatePasswordStrength } from '@bindshq/stance-react';
```

Styles are imported once per app: `@bindshq/stance-tokens/css` and `@bindshq/stance-react/styles.css`.

## Examples

### Sign in

```tsx
import { FormField, PasswordInput } from '@bindshq/stance-react';

export function SignIn() {
  return (
    <div style={{ width: '100%', maxWidth: 360 }}>
      <FormField label="Password" required>
        <PasswordInput />
      </FormField>
    </div>
  );
}
```

### With strength meter

```tsx
import { FormField, PasswordInput } from '@bindshq/stance-react';

export function Strength() {
  return (
    <div style={{ width: '100%', maxWidth: 360 }}>
      <FormField label="Create a password" description="At least 12 characters.">
        <PasswordInput strength autoComplete="new-password" defaultValue="Signed2026" />
      </FormField>
    </div>
  );
}
```

### Custom scoring

```tsx
import { FormField, PasswordInput } from '@bindshq/stance-react';

export function CustomScore() {
  return (
    <div style={{ width: '100%', maxWidth: 360 }}>
      <FormField label="Admin password" description="Admins need 16 characters or more.">
        <PasswordInput
          autoComplete="new-password"
          strength={(pw) =>
            pw.length >= 16
              ? { score: 4, label: 'Meets admin policy' }
              : { score: 1, label: `${16 - pw.length} more characters needed` }
          }
        />
      </FormField>
    </div>
  );
}
```

## API reference

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| PasswordInput | `strength` | `boolean \| ((password: string) => PasswordStrength)` | None | Show a strength meter, optionally with your own scorer. |
| PasswordInput | `visible` | `boolean` | None | Controlled visibility. |
| PasswordInput | `onVisibleChange` | `(visible: boolean) => void` | None | Called when the toggle is pressed. |
| PasswordInput | `showLabel / hideLabel` | `string` | `'Show password' / 'Hide password'` | Toggle labels. |
| PasswordInput | `autoComplete` | `string` | `'current-password'` | Use "new-password" on sign-up. |
| PasswordInput | `...props` | `InputProps` | None | All Input props except type and suffix. |
| estimatePasswordStrength | `(password) => PasswordStrength` | `function` | None | The default length-and-variety heuristic, score 0 to 4. |

## Accessibility

- The toggle is a real button with aria-pressed and a label that states the action ("Show password").
- Strength text is linked to the input with aria-describedby and updates in a polite live region.
- Strength is shown as both bars and words, never colour alone.
- Spell-check and auto-capitalisation are turned off so the password is not leaked to dictionaries.

## Keyboard

| Keys | Action |
| --- | --- |
| `Tab` | Moves from the field to the visibility toggle. |
| `Space` `Enter` | On the toggle: shows or hides the password. |

## Related

- https://stanceui.com/components/input
- https://stanceui.com/components/form-field