# Password Input

**A password field with a button that shows and hides what you typed.**

**Reference:** [View Source](https://github.com/jramke/fluid-primitives/tree/main/Resources/Private/Primitives/PasswordInput) · [Zag.js Docs](https://zagjs.com/components/react/password-input)

**PasswordInputExamples.html**

```html
<ui:passwordInput.root class="max-w-74">
    <ui:passwordInput.label>Password</ui:passwordInput.label>
    <ui:passwordInput.control>
        <ui:passwordInput.input />
        <ui:passwordInput.visibilityTrigger />
    </ui:passwordInput.control>
</ui:passwordInput.root>

```

## Features

- Toggles the password between hidden and plain text
- Keeps focus in the input when the visibility trigger is clicked, and leaves the trigger out of the tab order
- Hides the password again when its form is submitted or reset
- Sets `autocomplete` to `current-password` or `new-password` for browser autofill
- Keeps password managers away with `ignorePasswordManagers`
- Works with Field: takes its name, required, disabled, readonly and invalid state from it

## Anatomy

```html
<primitives:passwordInput.root>
    <primitives:passwordInput.label />
    <primitives:passwordInput.control>
        <primitives:passwordInput.input />
        <primitives:passwordInput.visibilityTrigger>
            <primitives:passwordInput.indicator />
        </primitives:passwordInput.visibilityTrigger>
    </primitives:passwordInput.control>
</primitives:passwordInput.root>
```

## Installation

```bash
typo3 ui:add passwordInput
```

Or copy the files manually from GitHub into your project: https://github.com/jramke/fluid-primitives/tree/main/Resources/Private/Registry/PasswordInput

Read more about installing [Components and Primitives](/docs/core-concepts/primitives.md).

## Examples

### Use it in a sign-up form

Nest `ui:passwordInput.root` in `ui:field.root`. The password input takes `name`, `required`, `disabled`, `invalid` and `aria-describedby` from the field. Set `autoComplete` to `new-password`, so the browser offers to generate a strong password. Type fewer than 12 characters in the demo and leave the input to see the error.

**PasswordInputExamples.html**

```html
<ui:field.root class="max-w-74" name="password" required="{true}">
    <ui:passwordInput.root autoComplete="{f:constant(name: 'Jramke\FluidPrimitives\Enum\PasswordAutoComplete::NewPassword')}">
        <ui:passwordInput.label>Choose a password</ui:passwordInput.label>
        <ui:passwordInput.control>
            <ui:passwordInput.input minlength="12" />
            <ui:passwordInput.visibilityTrigger />
        </ui:passwordInput.control>
    </ui:passwordInput.root>
    <ui:field.helperText>At least 12 characters.</ui:field.helperText>
    <ui:field.errorText />
</ui:field.root>

```

### Keep password managers away

Set `ignorePasswordManagers="{true}"` for a password that is not the visitor's own login, like the guest Wi-Fi password in the demo. 1Password, LastPass, Bitwarden, Dashlane and Proton Pass then leave the input alone. `defaultVisible="{true}"` shows the password when the page loads.

**PasswordInputExamples.html**

```html
<ui:passwordInput.root class="max-w-74" ignorePasswordManagers="{true}" defaultVisible="{true}">
    <ui:passwordInput.label>Guest Wi-Fi password</ui:passwordInput.label>
    <ui:passwordInput.control>
        <ui:passwordInput.input />
        <ui:passwordInput.visibilityTrigger />
    </ui:passwordInput.control>
</ui:passwordInput.root>

```

### Swap the icons

Put one `passwordInput.indicator` per state into the visibility trigger. The one matching the current state is shown.

```html
<primitives:passwordInput.visibilityTrigger>
    <primitives:passwordInput.indicator
        state="{f:constant(name: 'Jramke\FluidPrimitives\Enum\PasswordInputIndicatorState::Hidden')}"
        >Show</primitives:passwordInput.indicator
    >
    <primitives:passwordInput.indicator
        state="{f:constant(name: 'Jramke\FluidPrimitives\Enum\PasswordInputIndicatorState::Visible')}"
        >Hide</primitives:passwordInput.indicator
    >
</primitives:passwordInput.visibilityTrigger>
```

### Localization

The labels of the visibility trigger ship in the language file and follow the site language. Pass `translations` to override them for one password input: `visibilityTriggerLabelHidden` is read while the password is hidden ("Show password"), `visibilityTriggerLabelVisible` while it is shown.

```html
<f:variable
    name="passwordTranslations"
    value="{
        visibilityTriggerLabelHidden: '{f:translate(key: \'LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:forms.pin.show\')}',
        visibilityTriggerLabelVisible: '{f:translate(key: \'LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:forms.pin.hide\')}'
    }"
/>

<ui:passwordInput.root translations="{passwordTranslations}"> ... </ui:passwordInput.root>
```

## API Reference

### passwordInput.root

Provides shared password input state and wraps all related parts. Renders a `<div>` element.

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `disabled` | `boolean` | No | `-` | Whether the password input is disabled. Inherited from a surrounding field when available. |
| `invalid` | `boolean` | No | `-` | Whether the password input value is invalid. Inherited from a surrounding field when available. |
| `required` | `boolean` | No | `-` | Whether the password input is required. Inherited from a surrounding field when available. |
| `readOnly` | `boolean` | No | `-` | Whether the password input is readonly. Inherited from a surrounding field when available. |
| `name` | `string` | No | `-` | The name attribute of the password input. Useful for form submission. Inherited from a surrounding field when available. |
| `defaultVisible` | `boolean` | No | `false` | Whether the password is shown as plain text when rendered. |
| `autoComplete` | `Enum\PasswordAutoComplete` | No | `CurrentPassword` | The autocomplete attribute of the input. Use `new-password` on a sign-up or change-password form, so the browser offers to generate a password. |
| `ignorePasswordManagers` | `boolean` | No | `false` | Whether password managers leave the input alone. Works for 1Password, LastPass, Bitwarden, Dashlane and Proton Pass. |
| `translations` | `array` | No | `-` | Localized labels of the visibility trigger, `visibilityTriggerLabelHidden` and `visibilityTriggerLabelVisible`. A client script can pass a `visibilityTrigger` function of the visible state instead. Use `f:translate` for per-template localization overrides when needed. |
| `attributes` | `array` | No | `[]` | Additional attributes that should be rendered on the component where ui:attributes is used. |
| `asChild` | `boolean` | No | `-` | If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. |
| `rootId` | `string` | No | `-` | The root ID of the component, used for hydration and identification. |
| `ids` | `array` | No | `[]` | The IDs of of the component parts for composition. |
| `autoMount` | `boolean` | No | `true` | Whether the client initializes the component on its own. Set it to false to mount it yourself with `mount()` |
| `provider` | `string` | No | `-` | The `id` of the `.provider` this root takes its `rootId` and props from. |
| `class` | `string` | No | `-` | The CSS class(es) to be applied to the component. |

#### Rendered data attributes

| Attribute | Description |
| --- | --- |
| `data-password-input-root` | <uid> |
| `data-disabled` | Present when disabled |
| `data-invalid` | Present when invalid |
| `data-readonly` | Present when read-only |

### passwordInput.label

Labels the password input. Renders a `<label>` element.

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `attributes` | `array` | No | `[]` | Additional attributes that should be rendered on the component where ui:attributes is used. |
| `asChild` | `boolean` | No | `-` | If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. |
| `class` | `string` | No | `-` | The CSS class(es) to be applied to the component. |

#### Rendered data attributes

| Attribute | Description |
| --- | --- |
| `data-password-input-label` | <uid> |
| `data-disabled` | Present when disabled |
| `data-invalid` | Present when invalid |
| `data-readonly` | Present when read-only |
| `data-required` | Present when required |

### passwordInput.control

Groups the input and the visibility trigger. Renders a `<div>` element.

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `attributes` | `array` | No | `[]` | Additional attributes that should be rendered on the component where ui:attributes is used. |
| `asChild` | `boolean` | No | `-` | If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. |
| `class` | `string` | No | `-` | The CSS class(es) to be applied to the component. |

#### Rendered data attributes

| Attribute | Description |
| --- | --- |
| `data-password-input-control` | <uid> |
| `data-disabled` | Present when disabled |
| `data-invalid` | Present when invalid |
| `data-readonly` | Present when read-only |

### passwordInput.input

Provides the password input. Renders an `<input>` element.

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `attributes` | `array` | No | `[]` | Additional attributes that should be rendered on the component where ui:attributes is used. |
| `asChild` | `boolean` | No | `-` | If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. |
| `class` | `string` | No | `-` | The CSS class(es) to be applied to the component. |

#### Rendered data attributes

| Attribute | Description |
| --- | --- |
| `data-password-input-input` | <uid> |
| `data-state` | "visible" \| "hidden" |
| `data-disabled` | Present when disabled |
| `data-invalid` | Present when invalid |
| `data-readonly` | Present when read-only |

### passwordInput.visibilityTrigger

Shows or hides the password. Renders a `<button>` element.

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `attributes` | `array` | No | `[]` | Additional attributes that should be rendered on the component where ui:attributes is used. |
| `asChild` | `boolean` | No | `-` | If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. |
| `class` | `string` | No | `-` | The CSS class(es) to be applied to the component. |

#### Rendered data attributes

| Attribute | Description |
| --- | --- |
| `data-password-input-visibility-trigger` | <uid> |
| `data-readonly` | Present when read-only |
| `data-disabled` | Present when disabled |
| `data-state` | "visible" \| "hidden" |

### passwordInput.indicator

Shows content for one visibility state. Renders a `<span>` element.

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `state` | `Enum\PasswordInputIndicatorState` | Yes | `-` | The visibility state the indicator is shown in. |
| `attributes` | `array` | No | `[]` | Additional attributes that should be rendered on the component where ui:attributes is used. |
| `asChild` | `boolean` | No | `-` | If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. |
| `class` | `string` | No | `-` | The CSS class(es) to be applied to the component. |

#### Rendered data attributes

| Attribute | Description |
| --- | --- |
| `data-password-input-indicator` | <uid> |
| `data-state` | "visible" \| "hidden" |
| `data-disabled` | Present when disabled |
| `data-invalid` | Present when invalid |
| `data-readonly` | Present when read-only |

### Machine JavaScript API

| Name | Type | Description |
| --- | --- | --- |
| `visible` | `boolean` | Whether the password input is visible. |
| `disabled` | `boolean` | Whether the password input is disabled. |
| `invalid` | `boolean` | Whether the password input is invalid. |
| `focus` | `VoidFunction` | Focus the password input. |
| `setVisible` | `(value: boolean) => void` | Set the visibility of the password input. |
| `toggleVisible` | `VoidFunction` | Toggle the visibility of the password input. |
| `getRootState` | `() => RootState` | Returns the state of the root. |
| `getInputState` | `() => InputState` | Returns the state of the input. |
| `getVisibilityTriggerState` | `() => VisibilityTriggerState` | Returns the state of the visibility trigger. |