# PasswordInput

A password input is a specialized text field that masks user input to protect sensitive information like passwords, PINs, or security codes. It includes a toggle button to reveal or hide the password text for user convenience.

## When to Use

- Collect passwords, PINs, or other sensitive text data
- Provide secure input fields in login and registration forms
- Enable password creation with visibility toggle for verification
- Collect security codes or tokens that should be masked by default
- Offer accessible password entry with reveal functionality

## Component

---

### Properties

- **`value`** `string` — The password value in controlled mode
- **`defaultValue`** `string` — The default password value in uncontrolled mode
- **`placeholder`** `string` — Placeholder text when input is empty
- **`icon`** — Icon element rendered before the input
- **`prefix`** — Input decoration before the main input
- **`suffix`** — Input decoration after the main input (before toggle button)
- **`size`** `'small' | 'medium' | 'large'` (default: `medium`) — Input size
- **`isDisabled`** `boolean` (default: `false`) — Whether the input is disabled
- **`isReadOnly`** `boolean` (default: `false`) — Whether the input can be selected but not changed
- **`isRequired`** `boolean` (default: `false`) — Whether user input is required before form submission
- **`isLoading`** `boolean` (default: `false`) — Show loading spinner and disable interactions
- **`validationState`** `undefined | 'valid' | 'invalid'` — Whether the input should display valid or invalid visual styling
- **`autoFocus`** `boolean` (default: `false`) — Whether the element should receive focus on render
- **`onChange`** `function` — Callback fired when the input value changes
- **`onBlur`** `function` — Callback fired when the input loses focus
- **`onFocus`** `function` — Callback fired when the input receives focus

### Base Properties

Supports [Base properties](../../tasty/tasty.md)

### Styling Properties

#### styles

Customizes the root wrapper element of the component.

**Sub-elements:**
- `Prefix` - Element displayed before the input
- `Suffix` - Element displayed after the input (contains toggle button)
- `State` - Container for validation state indicators
- `InputIcon` - Icon displayed within the input area
- `ValidationIcon` - Icon displayed for validation state

#### inputStyles

Customizes the password input field specifically.

### Style Properties

The PasswordInput component supports all standard style properties:

`display`, `font`, `preset`, `hide`, `opacity`, `whiteSpace`, `gridArea`, `order`, `gridColumn`, `gridRow`, `placeSelf`, `alignSelf`, `justifySelf`, `zIndex`, `margin`, `inset`, `position`, `width`, `height`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`, `reset`, `padding`, `paddingInline`, `paddingBlock`, `shadow`, `border`, `radius`, `overflow`, `scrollbar`, `outline`, `textAlign`, `color`, `fill`, `fade`, `textTransform`, `fontWeight`, `fontStyle`, `flow`, `placeItems`, `placeContent`, `alignItems`, `alignContent`, `justifyItems`, `justifyContent`, `align`, `justify`, `gap`, `columnGap`, `rowGap`, `gridColumns`, `gridRows`, `gridTemplate`, `gridAreas`

### Modifiers

The `mods` property accepts the following modifiers you can override:

| Modifier | Type | Description |
|----------|------|-------------|
| focused | `boolean` | Whether the input has focus |
| disabled | `boolean` | Whether the password input is disabled |
| invalid | `boolean` | Whether the password input has validation errors |
| valid | `boolean` | Whether the password input is valid |
| hovered | `boolean` | Whether the password input is being hovered |
| inside-form | `boolean` | Whether the password input is inside a form field |

## Variants

### Sizes

- `small` - Compact size for dense interfaces
- `medium` - Standard size
- `large` - Emphasized size for important password fields

## Examples

### Basic Usage

```jsx
<PasswordInput
  label="Password"
  placeholder="Enter your password"
/>
```

### With Icon

```jsx
<PasswordInput
  label="Security Key"
  icon={<IconKey />}
  placeholder="Enter security key"
/>
```

### With Validation

```jsx
<PasswordInput
  label="New Password"
  isRequired
  validationState="invalid"
  errorMessage="Password must be at least 8 characters"
/>
```

### With Description

```jsx
<PasswordInput
  label="Password"
  description="Must be at least 8 characters with numbers and symbols"
  placeholder="Create a strong password"
/>
```

### Small Size

```jsx
<PasswordInput
  label="PIN"
  size="small"
  placeholder="Enter 4-digit PIN"
/>
```

### Disabled State

```jsx
<PasswordInput
  label="Disabled password"
  isDisabled
  value="hidden-password"
/>
```

### With Default Value

```jsx
<PasswordInput
  label="Current Password"
  defaultValue="existing-password"
/>
```

## Accessibility

### Keyboard Navigation

- `Tab` - Moves focus to the password input
- `Shift + Tab` - Moves focus to the toggle button
- `Enter` - Toggles password visibility when toggle button is focused
- `Space` - Toggles password visibility when toggle button is focused
- All standard text input keyboard shortcuts work for text entry

### Screen Reader Support

- Component announces as "password" input type to screen readers
- Toggle button announces its purpose ("Toggle masking", "Show password", "Hide password")
- Current visibility state is communicated when changed
- Validation errors and requirements are announced

### ARIA Properties

- `aria-label` - Provides accessible label when no visible label exists
- `aria-labelledby` - References external label elements
- `aria-describedby` - References additional descriptive text
- `aria-invalid` - Indicates validation state
- `aria-required` - Indicates if password entry is required
- Toggle button includes appropriate `aria-label` for its function

## Best Practices

1. **Do**: Provide clear password requirements and feedback
   ```jsx
   <PasswordInput
     label="New Password"
     description="8+ characters, including numbers and symbols"
     validationState={isValid ? "valid" : "invalid"}
   />
   ```

2. **Don't**: Use password input for non-sensitive data
   ```jsx
   <PasswordInput label="Username" /> {/* Use TextInput instead */}
   ```

3. **Security**: Always use HTTPS when handling password inputs
4. **Validation**: Provide real-time validation feedback for password creation
5. **Accessibility**: Ensure toggle button is easily accessible via keyboard
6. **UX**: Include the visibility toggle for better user experience

## Integration with Forms

This component supports all [Field properties](../form/Field.md) when used within a Form.

## Suggested Improvements

- Add password strength indicator with visual feedback
- Implement configurable password requirements validation
- Add support for custom toggle button icons or text
- Consider adding copy-to-clipboard functionality for generated passwords
- Implement password suggestion/generation features

## Related Components

- [TextInput](./TextInput.md) - For non-sensitive text input
- [NumberInput](./NumberInput.md) - For numeric PIN entries
- [SearchInput](./SearchInput.md) - For search functionality
