# Password Input

A password input with a button that shows and hides what's typed.

Source: [password-input.tsx](https://github.com/jakejarvis/jarvis-ui/blob/main/src/components/ui/password-input.tsx)

```tsx
import { Field, FieldLabel } from "@/components/ui/field";
import { PasswordInput } from "@/components/ui/password-input";

export default function PasswordInputBasic() {
  return (
    <Field className="max-w-sm">
      <FieldLabel>Password</FieldLabel>
      <PasswordInput autoComplete="current-password" defaultValue="correct-horse" />
    </Field>
  );
}
```

## Installation

Add the registry, once per project:

```bash
npx shadcn@latest registry add @jarvis=https://ui.jarv.is/r/{name}.json
```

Then add the component:

```bash
npx shadcn@latest add @jarvis/password-input
```

## Usage

```tsx
import { Field, FieldLabel } from "@/components/ui/field";
import { PasswordInput } from "@/components/ui/password-input";

export function SignInPassword() {
  return (
    <Field>
      <FieldLabel>Password</FieldLabel>
      <PasswordInput autoComplete="current-password" />
    </Field>
  );
}
```

Password Input is an [Input](https://ui.jarv.is/components/input.md) with an eye button at its end that switches the
input between `type="password"` and `type="text"`. Like [Secret Field](https://ui.jarv.is/components/secret-field.md)'s,
the button is a toggle that's pressed while the password is shown, so its label, `revealLabel`,
stays "Show password" in both states.

Password Input takes every prop Input does except `type`, including `size` and `variant`. The button
matches the input's size, variant and disabled state, including the disabled state of a
[Field](https://ui.jarv.is/components/field.md). `className`, `style` and `render` are applied to the wrapper around the
input and the button, and every other prop is passed to the input.

`autoComplete` tells password managers what to fill. It defaults to `current-password`, for signing
in. Set it to `new-password` for signing up or changing a password. Spellcheck, autocorrect and
autocapitalization are turned off, so a shown password isn't sent to a spellchecker or altered as
it's typed.

A shown password is hidden again when someone presses Escape, moves focus elsewhere on the page,
or submits or resets the form. This keeps it from being left on screen, or submitted from a `type="text"` input,
which password managers can miss. Switching to another window leaves it shown.

To show a secret that users can't edit, such as an API key, use Secret Field.

## Examples

### New password

```tsx
import { Field, FieldDescription, FieldLabel } from "@/components/ui/field";
import { PasswordInput } from "@/components/ui/password-input";

export default function PasswordInputNewPassword() {
  return (
    <Field className="max-w-sm">
      <FieldLabel>New password</FieldLabel>
      <PasswordInput autoComplete="new-password" minLength={12} defaultValue="battery-staple-42" />
      <FieldDescription>Use at least 12 characters.</FieldDescription>
    </Field>
  );
}
```

### Controlled

`revealed` and `onRevealedChange` control whether the password is shown, here for two fields at
once. `eventDetails.reason` says why the state changed, and canceling a `"focus-out"` change keeps
both passwords shown as focus moves between the fields.

```tsx
"use client";

import * as React from "react";

import { Checkbox } from "@/components/ui/checkbox";
import { Field, FieldGroup, FieldLabel } from "@/components/ui/field";
import {
  PasswordInput,
  type PasswordInputChangeEventDetails,
} from "@/components/ui/password-input";

export default function PasswordInputControlled() {
  const [revealed, setRevealed] = React.useState(false);

  const onRevealedChange = (next: boolean, eventDetails: PasswordInputChangeEventDetails) => {
    if (eventDetails.reason === "focus-out") eventDetails.cancel();
    else setRevealed(next);
  };

  return (
    <FieldGroup className="max-w-sm">
      <Field>
        <FieldLabel>New password</FieldLabel>
        <PasswordInput
          autoComplete="new-password"
          defaultValue="battery-staple-42"
          revealed={revealed}
          onRevealedChange={onRevealedChange}
        />
      </Field>
      <Field>
        <FieldLabel>Confirm password</FieldLabel>
        <PasswordInput
          autoComplete="new-password"
          defaultValue="battery-staple-42"
          revealed={revealed}
          onRevealedChange={onRevealedChange}
        />
      </Field>
      <Field orientation="horizontal">
        <Checkbox checked={revealed} onCheckedChange={(checked) => setRevealed(checked)} />
        <FieldLabel>Show passwords</FieldLabel>
      </Field>
    </FieldGroup>
  );
}
```

### Sizes

```tsx
import { PasswordInput } from "@/components/ui/password-input";

export default function PasswordInputSizes() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-4">
      <PasswordInput size="sm" aria-label="Small password" defaultValue="correct-horse" />
      <PasswordInput aria-label="Default password" defaultValue="correct-horse" />
      <PasswordInput size="lg" aria-label="Large password" defaultValue="correct-horse" />
    </div>
  );
}
```

### Invalid

```tsx
import { Field, FieldError, FieldLabel } from "@/components/ui/field";
import { PasswordInput } from "@/components/ui/password-input";

export default function PasswordInputInvalid() {
  return (
    <Field invalid className="max-w-sm">
      <FieldLabel>Password</FieldLabel>
      <PasswordInput autoComplete="new-password" defaultValue="hunter2" />
      <FieldError>Use at least 12 characters.</FieldError>
    </Field>
  );
}
```

### Disabled

```tsx
import { Field, FieldLabel } from "@/components/ui/field";
import { PasswordInput } from "@/components/ui/password-input";

export default function PasswordInputDisabled() {
  return (
    <Field disabled className="max-w-sm">
      <FieldLabel>Password</FieldLabel>
      <PasswordInput defaultValue="correct-horse" />
    </Field>
  );
}
```

## Props

| Part | Extends |
| --- | --- |
| `PasswordInput` | [`Input`](https://ui.jarv.is/components/input.md) |

Base UI's [styling](https://base-ui.com/react/handbook/styling) and [composition](https://base-ui.com/react/handbook/composition) guides say more about `className`, `style` and `render`.

### PasswordInput

| Prop                | Type                                                                                                                            | Default           | Description                                                                                                                                                                                                                                                                                                                                             |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onValueChange?`    | `((value: string, eventDetails: Input.ChangeEventDetails) => void)`                                                             | —                 | Callback fired when the `value` changes. Use when controlled.                                                                                                                                                                                                                                                                                           |
| `variant?`          | `"default" \| "underline"`                                                                                                      | `"default"`       |                                                                                                                                                                                                                                                                                                                                                         |
| `size?`             | `"default" \| "lg" \| "sm"`                                                                                                     | `"default"`       | The height: `sm` 24px, `default` 28px, `lg` 32px.                                                                                                                                                                                                                                                                                                       |
| `revealed?`         | `boolean`                                                                                                                       | —                 | Whether the password shows as plain text.                                                                                                                                                                                                                                                                                                               |
| `defaultRevealed?`  | `boolean`                                                                                                                       | `false`           | Whether the password shows as plain text at first, when `revealed` isn't set.                                                                                                                                                                                                                                                                           |
| `onRevealedChange?` | `((revealed: boolean, eventDetails: PasswordInputChangeEventDetails) => void)`                                                  | —                 | Called when the button beside the input shows or hides the password, and when a shown password is hidden again: on Escape (`"escape-key"`), when focus moves elsewhere on the page (`"focus-out"`) and when the form submits or resets (`"none"`). Calling `eventDetails.cancel()` keeps the password as it is.                                         |
| `revealLabel?`      | `string`                                                                                                                        | `"Show password"` | The button's `aria-label` and tooltip. They stay the same while the button is pressed and the password is shown.                                                                                                                                                                                                                                        |
| `className?`        | `string`                                                                                                                        | —                 | CSS class applied to the element.                                                                                                                                                                                                                                                                                                                       |
| `style?`            | `React.CSSProperties`                                                                                                           | —                 | Style applied to the element.                                                                                                                                                                                                                                                                                                                           |
| `render?`           | `((ComponentRenderFn<HTMLProps, InputState> \| React.ReactElement) & (ComponentRenderFn<HTMLProps, {}> \| React.ReactElement))` | —                 | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. Replaces the `<div>` that holds the input and its button with another element, or a function that renders one. `className` and `style` apply to this `<div>`. |
