Phone Field

Web/Mobile

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

Base UI React Aria Radix UI

Registry API Reference

شماره همراه

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

"use client"

import { SmartphoneIcon } from "lucide-react"

import {
  PhoneField,
  PhoneFieldClear,
  PhoneFieldControl,
  PhoneFieldDescription,
  PhoneFieldInput,
  PhoneFieldLabel,
} from "@/components/cubix/phone-field"

export function PhoneFieldDemo() {
  return (
    <PhoneField className="w-full max-w-sm">
      <PhoneFieldLabel>شماره همراه</PhoneFieldLabel>
      <PhoneFieldControl>
        <SmartphoneIcon data-icon="inline-start" />
        <PhoneFieldInput defaultValue="۰۹۱۲۳۴۵۶۷۸۹" placeholder="۰۹۱۲۰۰۰۰۰۰۰" />
        <PhoneFieldClear aria-label="پاک کردن" />
      </PhoneFieldControl>
      <PhoneFieldDescription>
        برای ورود و بازیابی حساب از این شماره استفاده می‌شود.
      </PhoneFieldDescription>
    </PhoneField>
  )
}

Installation

pnpm dlx cubix-ui@latest add phone-field --base radix

Usage

Import

import { SmartphoneIcon } from "lucide-react"

import {
  PhoneField,
  PhoneFieldClear,
  PhoneFieldControl,
  PhoneFieldDescription,
  PhoneFieldInput,
  PhoneFieldLabel,
} from "@/components/cubix/phone-field"

Example

<PhoneField className="w-full max-w-sm">
  <PhoneFieldLabel>شماره همراه</PhoneFieldLabel>
  <PhoneFieldControl>
    <SmartphoneIcon data-icon="inline-start" />
    <PhoneFieldInput defaultValue="۰۹۱۲۳۴۵۶۷۸۹" placeholder="۰۹۱۲۰۰۰۰۰۰۰" />
    <PhoneFieldClear aria-label="پاک کردن" />
  </PhoneFieldControl>
  <PhoneFieldDescription>
    برای ورود و بازیابی حساب از این شماره استفاده می‌شود.
  </PhoneFieldDescription>
</PhoneField>

Composition

Same composition as Text Field. PhoneFieldInput always renders type="tel" with telephone autocomplete and inputMode, so mobile keyboards open the dial pad.

Structure

PhoneField
├── PhoneFieldLabel
├── PhoneFieldControl
│   ├── Icon data-icon="inline-start" | "inline-end"
│   ├── PhoneFieldInput
│   └── PhoneFieldClear
├── PhoneFieldDescription
└── PhoneFieldError

Accessibility

PhoneFieldLabel is wired to the input, and PhoneFieldDescription and PhoneFieldError are announced through aria-describedby. invalid sets aria-invalid on the input. Give PhoneFieldClear 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 {
  PhoneField,
  PhoneFieldDescription,
  PhoneFieldInput,
  PhoneFieldLabel,
} from "@/components/cubix/phone-field"

export function PhoneFieldDescriptionDemo() {
  return (
    <PhoneField className="w-full max-w-sm">
      <PhoneFieldLabel>شماره همراه</PhoneFieldLabel>
      <PhoneFieldInput placeholder="۰۹۱۲۰۰۰۰۰۰۰" />
      <PhoneFieldDescription>شماره باید با ۰۹ شروع شود و ۱۱ رقم باشد.</PhoneFieldDescription>
    </PhoneField>
  )
}

Invalid

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

شماره همراه

یک شماره همراه معتبر وارد کنید.

"use client"

import { PhoneField, PhoneFieldError, PhoneFieldInput, PhoneFieldLabel } from "@/components/cubix/phone-field"

export function PhoneFieldInvalidDemo() {
  return (
    <PhoneField className="w-full max-w-sm" invalid>
      <PhoneFieldLabel>شماره همراه</PhoneFieldLabel>
      <PhoneFieldInput defaultValue="۰۹۱۲" placeholder="۰۹۱۲۰۰۰۰۰۰۰" />
      <PhoneFieldError>یک شماره همراه معتبر وارد کنید.</PhoneFieldError>
    </PhoneField>
  )
}

Disabled

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

شماره همراه

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

"use client"

import {
  PhoneField,
  PhoneFieldDescription,
  PhoneFieldInput,
  PhoneFieldLabel,
} from "@/components/cubix/phone-field"

export function PhoneFieldDisabledDemo() {
  return (
    <PhoneField className="w-full max-w-sm" disabled>
      <PhoneFieldLabel>شماره همراه</PhoneFieldLabel>
      <PhoneFieldInput defaultValue="۰۹۱۲۳۴۵۶۷۸۹" placeholder="۰۹۱۲۰۰۰۰۰۰۰" />
      <PhoneFieldDescription>این فیلد فعلاً قابل ویرایش نیست.</PhoneFieldDescription>
    </PhoneField>
  )
}

Sizes

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

شماره همراه

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

شماره همراه

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

"use client"

import { SmartphoneIcon } from "lucide-react"

import {
  PhoneField,
  PhoneFieldClear,
  PhoneFieldControl,
  PhoneFieldDescription,
  PhoneFieldInput,
  PhoneFieldLabel,
} from "@/components/cubix/phone-field"

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

export function PhoneFieldSizesDemo() {
  return (
    <div className="grid w-full max-w-sm gap-8">
      {sizes.map(({ size, hint }) => (
        <PhoneField key={size} size={size}>
          <PhoneFieldLabel>شماره همراه</PhoneFieldLabel>
          <PhoneFieldControl>
            <SmartphoneIcon data-icon="inline-start" />
            <PhoneFieldInput placeholder="۰۹۱۲۰۰۰۰۰۰۰" />
            <PhoneFieldClear aria-label="پاک کردن" />
          </PhoneFieldControl>
          <PhoneFieldDescription>{hint}</PhoneFieldDescription>
        </PhoneField>
      ))}
    </div>
  )
}

Icons

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

شماره همراه

شماره تماس اضطراری

"use client"

import { PhoneIcon, SmartphoneIcon } from "lucide-react"

import {
  PhoneField,
  PhoneFieldControl,
  PhoneFieldInput,
  PhoneFieldLabel,
} from "@/components/cubix/phone-field"

export function PhoneFieldIconsDemo() {
  return (
    <div className="grid w-full max-w-sm gap-8">
      <PhoneField>
        <PhoneFieldLabel>شماره همراه</PhoneFieldLabel>
        <PhoneFieldControl>
          <SmartphoneIcon data-icon="inline-start" />
          <PhoneFieldInput placeholder="۰۹۱۲۰۰۰۰۰۰۰" />
        </PhoneFieldControl>
      </PhoneField>
      <PhoneField>
        <PhoneFieldLabel>شماره تماس اضطراری</PhoneFieldLabel>
        <PhoneFieldControl>
          <PhoneFieldInput placeholder="۰۹۱۲۰۰۰۰۰۰۰" />
          <PhoneIcon data-icon="inline-end" />
        </PhoneFieldControl>
      </PhoneField>
    </div>
  )
}

Clear

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

شماره همراه

"use client"

import {
  PhoneField,
  PhoneFieldClear,
  PhoneFieldControl,
  PhoneFieldInput,
  PhoneFieldLabel,
} from "@/components/cubix/phone-field"

export function PhoneFieldClearDemo() {
  return (
    <PhoneField className="w-full max-w-sm">
      <PhoneFieldLabel>شماره همراه</PhoneFieldLabel>
      <PhoneFieldControl>
        <PhoneFieldInput defaultValue="۰۹۱۲۳۴۵۶۷۸۹" placeholder="۰۹۱۲۰۰۰۰۰۰۰" />
        <PhoneFieldClear aria-label="پاک کردن" />
      </PhoneFieldControl>
    </PhoneField>
  )
}

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

import { Button } from "@/components/cubix/button"
import {
  PhoneField,
  PhoneFieldClear,
  PhoneFieldControl,
  PhoneFieldDescription,
  PhoneFieldInput,
  PhoneFieldLabel,
} from "@/components/cubix/phone-field"

export function PhoneFieldFormDemo() {
  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>
      <PhoneField name="phone">
        <PhoneFieldLabel>شماره همراه</PhoneFieldLabel>
        <PhoneFieldControl>
          <SmartphoneIcon data-icon="inline-start" />
          <PhoneFieldInput placeholder="۰۹۱۲۰۰۰۰۰۰۰" required />
          <PhoneFieldClear aria-label="پاک کردن" />
        </PhoneFieldControl>
        <PhoneFieldDescription>یک شماره همراه معتبر وارد کنید.</PhoneFieldDescription>
      </PhoneField>
      <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 {
  PhoneField,
  PhoneFieldDescription,
  PhoneFieldInput,
  PhoneFieldLabel,
} from "@/components/cubix/phone-field"

export function PhoneFieldCustomDemo() {
  return (
    <PhoneField className="w-full max-w-sm">
      <PhoneFieldLabel>شماره همراه</PhoneFieldLabel>
      <PhoneFieldInput
        className="border-border bg-muted focus-visible:bg-background dark:bg-muted dark:focus-visible:bg-background"
        placeholder="۰۹۱۲۰۰۰۰۰۰۰"
      />
      <PhoneFieldDescription>با className می‌توانید ظاهر را سفارشی کنید.</PhoneFieldDescription>
    </PhoneField>
  )
}

API Reference

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

PhoneField

Prop	Type	Default	Description
size	"default" \| "lg"	"default"	Height for the input: default 40px, lg 48px. Inherited by PhoneFieldInput and PhoneFieldControl 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 PhoneFieldError 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).

PhoneFieldControl

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

PhoneFieldInput

Prop	Type	Default	Description
type	"tel"	"tel"	Locked to tel. Cannot be changed. inputMode is always tel and spellCheck is always false.
size	"default" \| "lg"	-	Overrides the size from PhoneField. Default 40px, lg 48px. Use className for other heights.
autoComplete	string	"tel"	Defaults to tel. Override only when a different telephone autocomplete token is required (for example tel-national).
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 telephone.

PhoneFieldClear

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).

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