# Password input

A password field with a button that shows or hides what was typed. The button says what pressing it will do ("Show", "Hide"), so its words change rather than a pressed state. It starts hidden, and hides again when its form is submitted, so the browser doesn't save what was typed as ordinary text. While Caps Lock is on, a note under the field says so, and the field is described by it.

Pass `autoComplete`: "current-password" to sign in, "new-password" to set one, so password managers fill it or offer one. Use `Field` for the label, hint and error.

- Registry name: `password-input` (`@candor/password-input`)
- Tier: Pro. Installing it needs a Pro, Premium or Team licence key: the person runs `npx candor-ui key <key>` themselves; never ask for the key in chat or write it to a file.
- Docs: https://candor.themethodic.com/docs/password-input

## Install

```bash
npx candor-ui add password-input
```

Run `npx candor-ui@latest init` once first (https://candor.themethodic.com/get-started.md). Without the CLI: `npx shadcn@latest add @candor/password-input`.
It brings in: button, input, locale, tokens, utils.
npm packages: lucide-react@^1.67.0.

## Example

```tsx
"use client"

import { Field } from "@/components/ui/field"
import { PasswordInput } from "@/components/ui/password-input"

// The button says what it will do. autoComplete tells a password manager whether to fill one or offer a new one.
export default function Example() {
  return (
    <Field label="API secret" hint="Stored encrypted. You can replace it, but not read it back." className="w-full max-w-sm">
      <PasswordInput name="secret" autoComplete="new-password" />
    </Field>
  )
}
```

## <PasswordInput>

Props:

- `attend?: boolean | undefined`: Rings the field once, as `Input`'s `attend` does, after a failed submit.
- `"aria-describedby"?: string | undefined`: Ids of anything else that describes the field; the Caps Lock note's id is added while it shows.

Also takes the props of `Omit<React.ComponentProps<"input">, "type">`.

## Strings (`passwordInput`)

The fixed words, English by default. Override any of them under `passwordInput` in `<LocaleProvider strings={{ passwordInput: { … } }}>`; the table is exported as `passwordInputStrings`.

- `show`: Show
- `hide`: Hide
- `showPassword`: Show password
- `hidePassword`: Hide password
- `capsLock`: Caps Lock is on.

## Rules for using Candor UI

- Components take plain typed data. Never pass model output as HTML or render it as a link; messages are typed blocks.
- A control that can't be used says why: wrap it in `<Locked reason="…">`, don't just disable it.
- Don't show a value you don't have: leave it out (it renders as —) rather than guess. An estimate is labelled as one.
- Nothing is pre-selected in a decision a person makes, and the agent is named from your app's data, never from model output.
- Your app's words go in `LocaleProvider` (fixed strings) and `TermsProvider` (nouns); entity kinds and agent roles in `EntityKindsProvider` and `AgentRolesProvider`.