Password Field

Web/Mobile

A labeled password field with icons, visibility toggle, description, and error. type switches between password and text when revealed.

Base UI React Aria Radix UI

Registry API Reference

رمز عبور

حداقل ۸ کاراکتر، شامل حرف و عدد.

"use client"

import { LockKeyholeIcon } from "lucide-react"

import {
  PasswordField,
  PasswordFieldControl,
  PasswordFieldDescription,
  PasswordFieldInput,
  PasswordFieldLabel,
  PasswordFieldToggle,
} from "@/components/cubix/password-field"

export function PasswordFieldDemo() {
  return (
    <PasswordField className="w-full max-w-sm">
      <PasswordFieldLabel>رمز عبور</PasswordFieldLabel>
      <PasswordFieldControl>
        <LockKeyholeIcon data-icon="inline-start" />
        <PasswordFieldInput defaultValue="CubixPass123!" placeholder="رمز عبور خود را وارد کنید" />
        <PasswordFieldToggle />
      </PasswordFieldControl>
      <PasswordFieldDescription>حداقل ۸ کاراکتر، شامل حرف و عدد.</PasswordFieldDescription>
    </PasswordField>
  )
}

Installation

pnpm dlx cubix-ui@latest add password-field

Usage

Import

import { LockKeyholeIcon } from "lucide-react"

import {
  PasswordField,
  PasswordFieldControl,
  PasswordFieldDescription,
  PasswordFieldInput,
  PasswordFieldLabel,
  PasswordFieldToggle,
} from "@/components/cubix/password-field"

Example

<PasswordField className="w-full max-w-sm">
  <PasswordFieldLabel>رمز عبور</PasswordFieldLabel>
  <PasswordFieldControl>
    <LockKeyholeIcon data-icon="inline-start" />
    <PasswordFieldInput defaultValue="CubixPass123!" placeholder="رمز عبور خود را وارد کنید" />
    <PasswordFieldToggle />
  </PasswordFieldControl>
  <PasswordFieldDescription>حداقل ۸ کاراکتر، شامل حرف و عدد.</PasswordFieldDescription>
</PasswordField>

Composition

Same composition as Text Field, with PasswordFieldToggle in place of the clear button. PasswordFieldInput starts as type="password" with current-password autocomplete and switches to text while revealed. The input defaults to dir="ltr" so trailing symbols stay in place in right-to-left forms.

Structure

PasswordField
├── PasswordFieldLabel
├── PasswordFieldControl
│   ├── Icon data-icon="inline-start" | "inline-end"
│   ├── PasswordFieldInput
│   └── PasswordFieldToggle
├── PasswordFieldDescription
└── PasswordFieldError

Accessibility

PasswordFieldToggle swaps its accessible name between showLabel and hideLabel and returns focus to the input after each press. PasswordFieldDescription and PasswordFieldError are announced through aria-describedby, and invalid sets aria-invalid on the input.

Examples

Visibility toggle

Pass defaultVisible on the root to start revealed.

رمز عبور

با دکمه چشم می‌توانید رمز را نمایش یا مخفی کنید.

"use client"

import {
  PasswordField,
  PasswordFieldControl,
  PasswordFieldDescription,
  PasswordFieldInput,
  PasswordFieldLabel,
  PasswordFieldToggle,
} from "@/components/cubix/password-field"

export function PasswordFieldToggleDemo() {
  return (
    <PasswordField className="w-full max-w-sm" defaultVisible>
      <PasswordFieldLabel>رمز عبور</PasswordFieldLabel>
      <PasswordFieldControl>
        <PasswordFieldInput defaultValue="CubixPass123!" placeholder="رمز عبور خود را وارد کنید" />
        <PasswordFieldToggle />
      </PasswordFieldControl>
      <PasswordFieldDescription>
        با دکمه چشم می‌توانید رمز را نمایش یا مخفی کنید.
      </PasswordFieldDescription>
    </PasswordField>
  )
}

Controlled

Pass visible and onVisibleChange to own the visibility state from outside.

رمز عبور

وضعیت: رمز عبور مخفی است

"use client"

import { useState } from "react"

import {
  PasswordField,
  PasswordFieldControl,
  PasswordFieldDescription,
  PasswordFieldInput,
  PasswordFieldLabel,
  PasswordFieldToggle,
} from "@/components/cubix/password-field"

export function PasswordFieldControlledDemo() {
  const [visible, setVisible] = useState(false)

  return (
    <PasswordField className="w-full max-w-sm" visible={visible} onVisibleChange={setVisible}>
      <PasswordFieldLabel>رمز عبور</PasswordFieldLabel>
      <PasswordFieldControl>
        <PasswordFieldInput defaultValue="CubixPass123!" placeholder="رمز عبور خود را وارد کنید" />
        <PasswordFieldToggle />
      </PasswordFieldControl>
      <PasswordFieldDescription>
        وضعیت: {visible ? "رمز عبور نمایش داده می‌شود" : "رمز عبور مخفی است"}
      </PasswordFieldDescription>
    </PasswordField>
  )
}

Description

Add helper text below the control for strength hints. Use autoComplete="new-password" when creating a password.

رمز عبور جدید

از ترکیب حروف بزرگ، کوچک، عدد و نماد استفاده کنید.

"use client"

import {
  PasswordField,
  PasswordFieldControl,
  PasswordFieldDescription,
  PasswordFieldInput,
  PasswordFieldLabel,
  PasswordFieldToggle,
} from "@/components/cubix/password-field"

export function PasswordFieldDescriptionDemo() {
  return (
    <PasswordField className="w-full max-w-sm">
      <PasswordFieldLabel>رمز عبور جدید</PasswordFieldLabel>
      <PasswordFieldControl>
        <PasswordFieldInput autoComplete="new-password" placeholder="رمز عبور جدید" />
        <PasswordFieldToggle />
      </PasswordFieldControl>
      <PasswordFieldDescription>
        از ترکیب حروف بزرگ، کوچک، عدد و نماد استفاده کنید.
      </PasswordFieldDescription>
    </PasswordField>
  )
}

Invalid

Set invalid on the root to apply destructive styles and show PasswordFieldError.

رمز عبور

رمز عبور باید حداقل ۸ کاراکتر باشد.

"use client"

import {
  PasswordField,
  PasswordFieldControl,
  PasswordFieldError,
  PasswordFieldInput,
  PasswordFieldLabel,
  PasswordFieldToggle,
} from "@/components/cubix/password-field"

export function PasswordFieldInvalidDemo() {
  return (
    <PasswordField className="w-full max-w-sm" invalid>
      <PasswordFieldLabel>رمز عبور</PasswordFieldLabel>
      <PasswordFieldControl>
        <PasswordFieldInput defaultValue="123" placeholder="رمز عبور خود را وارد کنید" />
        <PasswordFieldToggle />
      </PasswordFieldControl>
      <PasswordFieldError>رمز عبور باید حداقل ۸ کاراکتر باشد.</PasswordFieldError>
    </PasswordField>
  )
}

Disabled

Disable the field to block the input and toggle. The control uses a muted fill; label and description stay readable.

رمز عبور

این فیلد فعلاً قابل ویرایش نیست.

"use client"

import {
  PasswordField,
  PasswordFieldControl,
  PasswordFieldDescription,
  PasswordFieldInput,
  PasswordFieldLabel,
  PasswordFieldToggle,
} from "@/components/cubix/password-field"

export function PasswordFieldDisabledDemo() {
  return (
    <PasswordField className="w-full max-w-sm" disabled>
      <PasswordFieldLabel>رمز عبور</PasswordFieldLabel>
      <PasswordFieldControl>
        <PasswordFieldInput defaultValue="CubixPass123!" placeholder="رمز عبور خود را وارد کنید" />
        <PasswordFieldToggle />
      </PasswordFieldControl>
      <PasswordFieldDescription>این فیلد فعلاً قابل ویرایش نیست.</PasswordFieldDescription>
    </PasswordField>
  )
}

Sizes

Two heights ship by default: default (40px) and lg (48px). Use className for any other size.

رمز عبور

ارتفاع ۴۰ پیکسل

رمز عبور

ارتفاع ۴۸ پیکسل

"use client"

import { LockKeyholeIcon } from "lucide-react"

import {
  PasswordField,
  PasswordFieldControl,
  PasswordFieldDescription,
  PasswordFieldInput,
  PasswordFieldLabel,
  PasswordFieldToggle,
} from "@/components/cubix/password-field"

const sizes = [
  { size: "default", hint: "ارتفاع ۴۰ پیکسل" },
  { size: "lg", hint: "ارتفاع ۴۸ پیکسل" },
] as const

export function PasswordFieldSizesDemo() {
  return (
    <div className="grid w-full max-w-sm gap-8">
      {sizes.map(({ size, hint }) => (
        <PasswordField key={size} size={size}>
          <PasswordFieldLabel>رمز عبور</PasswordFieldLabel>
          <PasswordFieldControl>
            <LockKeyholeIcon data-icon="inline-start" />
            <PasswordFieldInput placeholder="رمز عبور خود را وارد کنید" />
            <PasswordFieldToggle />
          </PasswordFieldControl>
          <PasswordFieldDescription>{hint}</PasswordFieldDescription>
        </PasswordField>
      ))}
    </div>
  )
}

Icons

Place icons inside PasswordFieldControl with data-icon like Button so spacing follows the reading direction.

کلید دسترسی

"use client"

import { KeyRoundIcon } from "lucide-react"

import {
  PasswordField,
  PasswordFieldControl,
  PasswordFieldInput,
  PasswordFieldLabel,
  PasswordFieldToggle,
} from "@/components/cubix/password-field"

export function PasswordFieldIconsDemo() {
  return (
    <PasswordField className="w-full max-w-sm">
      <PasswordFieldLabel>کلید دسترسی</PasswordFieldLabel>
      <PasswordFieldControl>
        <KeyRoundIcon data-icon="inline-start" />
        <PasswordFieldInput placeholder="کلید را وارد کنید" />
        <PasswordFieldToggle />
      </PasswordFieldControl>
    </PasswordField>
  )
}

In a form

Set name on the root so the value is submitted with the form, and pair the field with Cubix Button.

"use client"

import { LockKeyholeIcon } from "lucide-react"

import { Button } from "@/components/cubix/button"
import {
  PasswordField,
  PasswordFieldControl,
  PasswordFieldDescription,
  PasswordFieldInput,
  PasswordFieldLabel,
  PasswordFieldToggle,
} from "@/components/cubix/password-field"

export function PasswordFieldFormDemo() {
  return (
    <form
      className="grid w-full max-w-xs gap-6 rounded-xl bg-background p-6"
      onSubmit={(event) => event.preventDefault()}
    >
      <div className="space-y-1.5">
        <p className="text-body leading-none font-medium text-foreground">ورود به حساب</p>
        <p className="text-caption text-muted-foreground">رمز عبور حساب Cubix خود را وارد کنید.</p>
      </div>
      <PasswordField name="password">
        <PasswordFieldLabel>رمز عبور</PasswordFieldLabel>
        <PasswordFieldControl>
          <LockKeyholeIcon data-icon="inline-start" />
          <PasswordFieldInput placeholder="رمز عبور خود را وارد کنید" required />
          <PasswordFieldToggle />
        </PasswordFieldControl>
        <PasswordFieldDescription>حداقل ۸ کاراکتر، شامل حرف و عدد.</PasswordFieldDescription>
      </PasswordField>
      <div className="grid grid-cols-2 gap-2">
        <Button type="button" variant="outline">
          انصراف
        </Button>
        <Button type="submit">ورود</Button>
      </div>
    </form>
  )
}

Custom styling

Every part accepts a className merged with the shipped cn helper. When the toggle sits in the control, style PasswordFieldControl for a filled surface instead of the default outline.

رمز عبور

با className می‌توانید ظاهر را سفارشی کنید.

"use client"

import {
  PasswordField,
  PasswordFieldControl,
  PasswordFieldDescription,
  PasswordFieldInput,
  PasswordFieldLabel,
  PasswordFieldToggle,
} from "@/components/cubix/password-field"

export function PasswordFieldCustomDemo() {
  return (
    <PasswordField className="w-full max-w-sm">
      <PasswordFieldLabel>رمز عبور</PasswordFieldLabel>
      <PasswordFieldControl className="border-border bg-muted has-[[data-slot=password-field-input]:focus-visible]:bg-background dark:bg-muted dark:has-[[data-slot=password-field-input]:focus-visible]:bg-background">
        <PasswordFieldInput placeholder="رمز عبور خود را وارد کنید" />
        <PasswordFieldToggle />
      </PasswordFieldControl>
      <PasswordFieldDescription>
        با className می‌توانید ظاهر را سفارشی کنید.
      </PasswordFieldDescription>
    </PasswordField>
  )
}

API Reference

Note: Parts render data-slot attributes (password-field, password-field-label, password-field-control, password-field-input, password-field-toggle, password-field-description, password-field-error) for targeting in tests and parent selectors. Use the same props on Base UI, React Aria, and Radix.

PasswordField

Prop	Type	Default	Description
size	"default" \| "lg"	"default"	Height for the input: default 40px, lg 48px. Inherited by PasswordFieldInput and PasswordFieldControl unless overridden. Use className for other heights.
disabled	boolean	false	Disables the field, input, and visibility toggle. Forwarded on every base.
invalid	boolean	false	Marks the field as invalid and shows PasswordFieldError when present.
visible	boolean	-	Controlled visibility. When true, the input type is text; when false, password. Pair with onVisibleChange.
defaultVisible	boolean	false	Initial visibility for uncontrolled use. Defaults to hidden (password).
onVisibleChange	(visible: boolean) => void	-	Called when PasswordFieldToggle changes visibility.
name	string	-	Identifies the field when a form is submitted. Forwarded to the input on every base.
className	string	-	Additional Tailwind classes merged with the root styles (last one wins).

PasswordFieldControl

Prop	Type	Default	Description
size	"default" \| "lg"	-	Overrides the size from PasswordField. Icon inset and height match the default and lg sizes.
children	React.ReactNode	-	Wrap PasswordFieldInput with icons marked data-icon="inline-start" or "inline-end" (same as Button), and PasswordFieldToggle.
className	string	-	Additional Tailwind classes merged with the control styles (last one wins).

PasswordFieldInput

Prop	Type	Default	Description
type	"password" \| "text"	"password"	Locked to password when hidden and text when PasswordFieldToggle reveals the value. Cannot be set manually. spellCheck is always false.
size	"default" \| "lg"	-	Overrides the size from PasswordField. Default 40px, lg 48px. Use className for other heights.
autoComplete	string	"current-password"	Defaults to current-password. Use "new-password" for create or reset flows.
dir	"ltr" \| "rtl" \| "auto"	"ltr"	Passwords are typed in Latin, so the input defaults to ltr and trailing symbols stay in place when the value is revealed. Text still aligns with the surrounding form direction.
placeholder	string	-	Hint text shown when the input is empty.
className	string	-	Additional Tailwind classes merged with the input styles (last one wins).
...props	Omit<React.ComponentProps<'input'>, 'type' \| 'spellCheck'>	-	Native input attributes (value, onChange, name, required, ...) are forwarded. type and spellCheck stay locked.

PasswordFieldToggle

Prop	Type	Default	Description
showLabel	string	"نمایش رمز عبور"	Accessible name while the password is hidden. Used as aria-label on the toggle, which swaps names instead of using aria-pressed.
hideLabel	string	"مخفی کردن رمز عبور"	Accessible name while the password is visible. Used as aria-label on the toggle.
className	string	-	Additional Tailwind classes merged with the toggle button styles (last one wins).

PasswordFieldLabel / Description / Error

Prop	Type	Default	Description
className	string	-	Additional Tailwind classes merged with the part styles (last one wins).
...props	HTML attributes	-	Native attributes for the rendered element are forwarded.