Email Field

Web/Mobile

A labeled email field with icons, clear, description, and error. type is locked to email with matching autocomplete and inputMode.

Base UI React Aria Radix UI

Registry API Reference

ایمیل

برای ورود و بازیابی حساب از این ایمیل استفاده می‌شود.

"use client"

import { MailIcon } from "lucide-react"

import {
  EmailField,
  EmailFieldClear,
  EmailFieldControl,
  EmailFieldDescription,
  EmailFieldInput,
  EmailFieldLabel,
} from "@/components/cubix/email-field"

export function EmailFieldDemo() {
  return (
    <EmailField className="w-full max-w-sm">
      <EmailFieldLabel>ایمیل</EmailFieldLabel>
      <EmailFieldControl>
        <MailIcon data-icon="inline-start" />
        <EmailFieldInput defaultValue="amin@cubix.com" placeholder="example@cubix.com" />
        <EmailFieldClear aria-label="پاک کردن" />
      </EmailFieldControl>
      <EmailFieldDescription>
        برای ورود و بازیابی حساب از این ایمیل استفاده می‌شود.
      </EmailFieldDescription>
    </EmailField>
  )
}

Installation

pnpm dlx cubix-ui@latest add email-field --base aria

Usage

Import

import { MailIcon } from "lucide-react"

import {
  EmailField,
  EmailFieldClear,
  EmailFieldControl,
  EmailFieldDescription,
  EmailFieldInput,
  EmailFieldLabel,
} from "@/components/cubix/email-field"

Example

<EmailField className="w-full max-w-sm">
  <EmailFieldLabel>ایمیل</EmailFieldLabel>
  <EmailFieldControl>
    <MailIcon data-icon="inline-start" />
    <EmailFieldInput defaultValue="amin@cubix.com" placeholder="example@cubix.com" />
    <EmailFieldClear aria-label="پاک کردن" />
  </EmailFieldControl>
  <EmailFieldDescription>
    برای ورود و بازیابی حساب از این ایمیل استفاده می‌شود.
  </EmailFieldDescription>
</EmailField>

Composition

Same composition as Text Field. EmailFieldInput always renders type="email" with email autocomplete and inputMode. Addresses are Latin, so the input defaults to dir="ltr" while the text stays aligned with the surrounding form - a trailing @ or . no longer jumps to the wrong side in right-to-left forms.

Structure

EmailField
├── EmailFieldLabel
├── EmailFieldControl
│   ├── Icon data-icon="inline-start" | "inline-end"
│   ├── EmailFieldInput
│   └── EmailFieldClear
├── EmailFieldDescription
└── EmailFieldError

Accessibility

EmailFieldLabel is wired to the input, and EmailFieldDescription and EmailFieldError are announced through aria-describedby. invalid sets aria-invalid on the input. Give EmailFieldClear a localized aria-label; it leaves the tab order while hidden.

Examples

Description

Add helper text below the control for format hints or guidance.

ایمیل کاریترجیحاً از ایمیل سازمانی خود استفاده کنید.

"use client"

import {
  EmailField,
  EmailFieldDescription,
  EmailFieldInput,
  EmailFieldLabel,
} from "@/components/cubix/email-field"

export function EmailFieldDescriptionDemo() {
  return (
    <EmailField className="w-full max-w-sm">
      <EmailFieldLabel>ایمیل کاری</EmailFieldLabel>
      <EmailFieldInput placeholder="name@company.com" />
      <EmailFieldDescription>ترجیحاً از ایمیل سازمانی خود استفاده کنید.</EmailFieldDescription>
    </EmailField>
  )
}

Invalid

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

ایمیلیک آدرس ایمیل معتبر وارد کنید.

"use client"

import { EmailField, EmailFieldError, EmailFieldInput, EmailFieldLabel } from "@/components/cubix/email-field"

export function EmailFieldInvalidDemo() {
  return (
    <EmailField className="w-full max-w-sm" invalid>
      <EmailFieldLabel>ایمیل</EmailFieldLabel>
      <EmailFieldInput defaultValue="amin@" placeholder="example@cubix.com" />
      <EmailFieldError>یک آدرس ایمیل معتبر وارد کنید.</EmailFieldError>
    </EmailField>
  )
}

Disabled

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

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

"use client"

import {
  EmailField,
  EmailFieldDescription,
  EmailFieldInput,
  EmailFieldLabel,
} from "@/components/cubix/email-field"

export function EmailFieldDisabledDemo() {
  return (
    <EmailField className="w-full max-w-sm" disabled>
      <EmailFieldLabel>ایمیل</EmailFieldLabel>
      <EmailFieldInput defaultValue="amin@cubix.com" placeholder="example@cubix.com" />
      <EmailFieldDescription>این فیلد فعلاً قابل ویرایش نیست.</EmailFieldDescription>
    </EmailField>
  )
}

Sizes

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

ایمیل

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

ایمیل

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

"use client"

import { MailIcon } from "lucide-react"

import {
  EmailField,
  EmailFieldClear,
  EmailFieldControl,
  EmailFieldDescription,
  EmailFieldInput,
  EmailFieldLabel,
} from "@/components/cubix/email-field"

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

export function EmailFieldSizesDemo() {
  return (
    <div className="grid w-full max-w-sm gap-8">
      {sizes.map(({ size, hint }) => (
        <EmailField key={size} size={size}>
          <EmailFieldLabel>ایمیل</EmailFieldLabel>
          <EmailFieldControl>
            <MailIcon data-icon="inline-start" />
            <EmailFieldInput placeholder="example@cubix.com" />
            <EmailFieldClear aria-label="پاک کردن" />
          </EmailFieldControl>
          <EmailFieldDescription>{hint}</EmailFieldDescription>
        </EmailField>
      ))}
    </div>
  )
}

Icons

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

ایمیل

ایمیل پشتیبان

"use client"

import { AtSignIcon, MailIcon } from "lucide-react"

import {
  EmailField,
  EmailFieldControl,
  EmailFieldInput,
  EmailFieldLabel,
} from "@/components/cubix/email-field"

export function EmailFieldIconsDemo() {
  return (
    <div className="grid w-full max-w-sm gap-8">
      <EmailField>
        <EmailFieldLabel>ایمیل</EmailFieldLabel>
        <EmailFieldControl>
          <MailIcon data-icon="inline-start" />
          <EmailFieldInput placeholder="example@cubix.com" />
        </EmailFieldControl>
      </EmailField>
      <EmailField>
        <EmailFieldLabel>ایمیل پشتیبان</EmailFieldLabel>
        <EmailFieldControl>
          <EmailFieldInput placeholder="backup@cubix.com" />
          <AtSignIcon data-icon="inline-end" />
        </EmailFieldControl>
      </EmailField>
    </div>
  )
}

Clear

EmailFieldClear appears inside the control while the input has a value and returns focus to the input after clearing.

ایمیل

"use client"

import {
  EmailField,
  EmailFieldClear,
  EmailFieldControl,
  EmailFieldInput,
  EmailFieldLabel,
} from "@/components/cubix/email-field"

export function EmailFieldClearDemo() {
  return (
    <EmailField className="w-full max-w-sm">
      <EmailFieldLabel>ایمیل</EmailFieldLabel>
      <EmailFieldControl>
        <EmailFieldInput defaultValue="amin@cubix.com" placeholder="example@cubix.com" />
        <EmailFieldClear aria-label="پاک کردن" />
      </EmailFieldControl>
    </EmailField>
  )
}

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 { MailIcon } from "lucide-react"

import { Button } from "@/components/cubix/button"
import {
  EmailField,
  EmailFieldClear,
  EmailFieldControl,
  EmailFieldDescription,
  EmailFieldInput,
  EmailFieldLabel,
} from "@/components/cubix/email-field"

export function EmailFieldFormDemo() {
  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">لینک ورود به این آدرس ارسال می‌شود.</p>
      </div>
      <EmailField name="email">
        <EmailFieldLabel>ایمیل</EmailFieldLabel>
        <EmailFieldControl>
          <MailIcon data-icon="inline-start" />
          <EmailFieldInput placeholder="example@cubix.com" required />
          <EmailFieldClear aria-label="پاک کردن" />
        </EmailFieldControl>
        <EmailFieldDescription>یک آدرس ایمیل معتبر وارد کنید.</EmailFieldDescription>
      </EmailField>
      <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. Here the input uses a filled surface instead of the default outline.

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

"use client"

import {
  EmailField,
  EmailFieldDescription,
  EmailFieldInput,
  EmailFieldLabel,
} from "@/components/cubix/email-field"

export function EmailFieldCustomDemo() {
  return (
    <EmailField className="w-full max-w-sm">
      <EmailFieldLabel>ایمیل</EmailFieldLabel>
      <EmailFieldInput
        className="border-border bg-muted focus-visible:bg-background dark:bg-muted dark:focus-visible:bg-background"
        placeholder="example@cubix.com"
      />
      <EmailFieldDescription>با className می‌توانید ظاهر را سفارشی کنید.</EmailFieldDescription>
    </EmailField>
  )
}

API Reference

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

EmailField

Prop	Type	Default	Description
size	"default" \| "lg"	"default"	Height for the input: default 40px, lg 48px. Inherited by EmailFieldInput and EmailFieldControl unless overridden. Use className for other heights.
disabled	boolean	false	Disables the field and prevents interaction. Forwarded to the control on every base.
invalid	boolean	false	Marks the field as invalid and shows EmailFieldError when present.
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).

EmailFieldControl

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

EmailFieldInput

Prop	Type	Default	Description
type	"email"	"email"	Locked to email. Cannot be changed. inputMode is always email and spellCheck is always false.
size	"default" \| "lg"	-	Overrides the size from EmailField. Default 40px, lg 48px. Use className for other heights.
autoComplete	string	"email"	Defaults to email. Override only when a different email autocomplete token is required.
dir	"ltr" \| "rtl" \| "auto"	"ltr"	Addresses are Latin, so the input defaults to ltr and a trailing @ or . stays in place while typing. 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' \| 'inputMode' \| 'spellCheck'>	-	Native input attributes (value, onChange, name, required, ...) are forwarded. type, inputMode, and spellCheck stay locked for email.

EmailFieldClear

Prop	Type	Default	Description
aria-label	string	"Clear"	Accessible name for the clear button. Required when no visible text is present.
className	string	-	Additional Tailwind classes merged with the clear button styles (last one wins).

EmailFieldLabel / 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.