PasswordField

Summary

PasswordField is a compound component built on TextField. It adds password visibility state, a toggle button, and icon parts while keeping the actual input native. It is the secret-entry layer when masked review is part of the field contract.

Imports

import {
  PasswordField,
  PasswordFieldHiddenIcon,
  PasswordFieldInput,
  PasswordFieldShownIcon,
  PasswordFieldToggleIconButton,
  type PasswordFieldHiddenIconProps,
  type PasswordFieldInputProps,
  type PasswordFieldProps,
  type PasswordFieldShownIconProps,
  type PasswordFieldToggleIconButtonProps,
} from '@vega-ui/react';

Exported Types

• PasswordFieldProps
• PasswordFieldInputProps
• PasswordFieldToggleIconButtonProps
• PasswordFieldShownIconProps
• PasswordFieldHiddenIconProps

Minimal Composition

import {
  Label,
  PasswordField,
  PasswordFieldHiddenIcon,
  PasswordFieldInput,
  PasswordFieldShownIcon,
  PasswordFieldToggleIconButton,
} from '@vega-ui/react';
import { useId } from 'react';

export default function SignInPassword() {
  const id = useId();

Required Parts

• PasswordField: root state container
• PasswordFieldInput: native password input
• PasswordFieldToggleIconButton: visibility toggle

Optional Parts

• PasswordFieldShownIcon: shown-state icon
• PasswordFieldHiddenIcon: hidden-state icon

Composition Order

1. PasswordField
2. PasswordFieldInput
3. PasswordFieldToggleIconButton
4. shown/hidden icon parts

Variants

• Size: inherited from TextField
• State: hidden or shown password, disabled, error through root field props
• Composition: default icons or custom icon content

Edge Cases

• Visibility toggling should preserve focus on the input.
• Password managers and autofill behavior should be tested in real browsers.
• Showing the password helps review input, but it is not a security control by itself.
• Validation policy, strength hints, and reveal behavior should stay clearly separated in the product model.

Common Mistakes

• Rendering the toggle without an accessible label.
• Assuming password strength hints are the same as actual validation policy.
• Replacing the compound parts with custom wrappers before the basic composition works.

Examples

Basic

Basic: sign-in password

id, name and autoComplete='current-password' go on PasswordFieldInput, so the Label and password managers find the real input. The toggle has no built-in name: give it a fixed aria-label such as "Show password" — it already exposes its state with aria-pressed.

import {
  Label,
  PasswordField,
  PasswordFieldHiddenIcon,
  PasswordFieldInput,
  PasswordFieldShownIcon,
  PasswordFieldToggleIconButton,
} from '@vega-ui/react';
import { useId } from 'react';

export default function SignInPassword() {
  const id = useId();

Controlled/Stateful

Controlled/Stateful: live requirement checklist

The parent owns the value and checks each rule on every keystroke. The checklist is linked to the input with aria-describedby, and the count below is a status region.

import {
  Icon,
  Label,
  PasswordField,
  PasswordFieldHiddenIcon,
  PasswordFieldInput,
  PasswordFieldShownIcon,
  PasswordFieldToggleIconButton,
  Text,
} from '@vega-ui/react';
import { CheckIcon, CircleIcon } from '@vega-ui/icons';
import { useId, useState } from 'react';

Controlled/Stateful: one toggle for two fields

shown and onChangeShown lift the visibility into the parent. The toggle in the first field reveals both, and the confirmation field has no toggle of its own.

import {
  Label,
  PasswordField,
  PasswordFieldHiddenIcon,
  PasswordFieldInput,
  PasswordFieldShownIcon,
  PasswordFieldToggleIconButton,
} from '@vega-ui/react';
import { useId, useState } from 'react';

export default function OneToggleForTwoFields() {
  const id = useId();

Form/Integration

Form/Integration: sign-in form

An email field with autoComplete='username' next to the password lets password managers save and fill both. The form reads both values with FormData and hides the password again on submit, so it is never left on screen as plain text.

import {
  Button,
  Label,
  PasswordField,
  PasswordFieldHiddenIcon,
  PasswordFieldInput,
  PasswordFieldShownIcon,
  PasswordFieldToggleIconButton,
  Text,
  TextField,
  TextFieldInput,
} from '@vega-ui/react';

Layout/Overlay

Layout/Overlay: confirm a sensitive action in a dialog

The dialog stays open on a wrong password and shows the error under the field; a correct one closes it through the controlled open. The error clears whenever the dialog closes. Try vega-demo.

import type { CSSProperties, FormEvent } from 'react';
import {
  Button,
  Dialog,
  DialogClose,
  DialogContent,
  DialogTrigger,
  Heading,
  HelperText,
  Icon,
  IconButton,
  Label,

Error

Error: confirmation does not match

The mismatch is derived from both values, but it appears only after the confirmation field loses focus or the form is submitted. error paints the field, and aria-invalid with aria-describedby tells screen readers what is wrong.

import {
  Button,
  HelperText,
  Label,
  PasswordField,
  PasswordFieldHiddenIcon,
  PasswordFieldInput,
  PasswordFieldShownIcon,
  PasswordFieldToggleIconButton,
} from '@vega-ui/react';
import { FormEvent, useId, useState } from 'react';

Disabled

Disabled: managed by single sign-on

disabled on the root disables the input and the toggle together. The hint explains why the field is locked and where to change the password.

import {
  HelperText,
  Label,
  PasswordField,
  PasswordFieldHiddenIcon,
  PasswordFieldInput,
  PasswordFieldShownIcon,
  PasswordFieldToggleIconButton,
} from '@vega-ui/react';
import { useId } from 'react';

export default function ManagedBySso() {

Edge

Edge: Caps Lock warning

A masked password hides typing mistakes, so warn when Caps Lock is on. getModifierState('CapsLock') is read in the key handlers, and the warning is a polite live region linked to the input.

import {
  HelperText,
  Label,
  PasswordField,
  PasswordFieldHiddenIcon,
  PasswordFieldInput,
  PasswordFieldShownIcon,
  PasswordFieldToggleIconButton,
} from '@vega-ui/react';
import { KeyboardEvent, useId, useState } from 'react';

export default function CapsLockWarning() {

Anatomy

Overview

PasswordField extends the TextField composition contract with one extra state model: whether the password is currently shown or hidden.

Required Parts

PasswordField

Required. Owns visibility state and provides context to the child parts.

PasswordFieldInput

Required. Switches between type='password' and type='text' based on context.

PasswordFieldToggleIconButton

Required in normal composition. Triggers visibility changes.

Optional Parts

PasswordFieldShownIcon

Optional icon for the shown state.

PasswordFieldHiddenIcon

Optional icon for the hidden state.

Composition Order

1. PasswordField
2. PasswordFieldInput
3. PasswordFieldToggleIconButton
4. PasswordFieldShownIcon
5. PasswordFieldHiddenIcon

Valid Composition Patterns

import {
  Label,
  PasswordField,
  PasswordFieldHiddenIcon,
  PasswordFieldInput,
  PasswordFieldShownIcon,
  PasswordFieldToggleIconButton,
} from '@vega-ui/react';
import { useId } from 'react';

export default function SignInPassword() {
  const id = useId();

Invalid Composition Patterns

Toggle without the input

The control renders a button, but there is no actual password field.

Custom button without preserving the toggle contract

The root state exists, but the user loses the standard shown/hidden affordance.

Hidden or shown icons rendered outside the toggle

The icons should stay part of the one clickable control.