Text Field

Web/Mobile

A labeled plain-text field with optional icons, clear, description, and error - for names, usernames, and other free text. Email, phone, password, and similar inputs are separate components.

Base UI React Aria Radix UI

Registry API Reference

نام و نام خانوادگی

نام کامل خود را وارد کنید.

"use client"

import {
  TextField,
  TextFieldClear,
  TextFieldControl,
  TextFieldDescription,
  TextFieldInput,
  TextFieldLabel,
} from "@/components/cubix/text-field"

export function TextFieldDemo() {
  return (
    <TextField className="w-full max-w-sm">
      <TextFieldLabel>نام و نام خانوادگی</TextFieldLabel>
      <TextFieldControl>
        <Icon data-icon="inline-start" />
        <TextFieldInput defaultValue="امین ابدالی" placeholder="نام کامل" />
        <TextFieldClear aria-label="پاک کردن" />
      </TextFieldControl>
      <TextFieldDescription>نام کامل خود را وارد کنید.</TextFieldDescription>
    </TextField>
  )
}

Installation

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

Usage

Import

import {
  TextField,
  TextFieldClear,
  TextFieldControl,
  TextFieldDescription,
  TextFieldInput,
  TextFieldLabel,
} from "@/components/cubix/text-field"

Example

<TextField className="w-full max-w-sm">
  <TextFieldLabel>نام و نام خانوادگی</TextFieldLabel>
  <TextFieldControl>
    <Icon data-icon="inline-start" />
    <TextFieldInput defaultValue="امین ابدالی" placeholder="نام کامل" />
    <TextFieldClear aria-label="پاک کردن" />
  </TextFieldControl>
  <TextFieldDescription>نام کامل خود را وارد کنید.</TextFieldDescription>
</TextField>

Composition

Compose label, control, help text, and error as siblings under TextField. Wrap the input in TextFieldControl when you need icons or a clear button - mark icons with data-icon like Button so spacing follows the reading direction. TextFieldClear appears only while the input has a value.

Structure

TextField
├── TextFieldLabel
├── TextFieldControl
│   ├── Icon data-icon="inline-start" | "inline-end"
│   ├── TextFieldInput
│   └── TextFieldClear
├── TextFieldDescription
└── TextFieldError

Accessibility

TextFieldLabel is wired to the input, and TextFieldDescription and TextFieldError are announced through aria-describedby. invalid sets aria-invalid on the input. Give TextFieldClear 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 { TextField, TextFieldDescription, TextFieldInput, TextFieldLabel } from "@/components/cubix/text-field"

export function TextFieldDescriptionDemo() {
  return (
    <TextField className="w-full max-w-sm">
      <TextFieldLabel>نام کاربری</TextFieldLabel>
      <TextFieldInput dir="ltr" placeholder="amin" autoComplete="username" />
      <TextFieldDescription>فقط حروف انگلیسی، عدد و زیرخط مجاز است.</TextFieldDescription>
    </TextField>
  )
}

Invalid

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

نام کاربریفقط حروف انگلیسی، عدد و زیرخط مجاز است.

"use client"

import { TextField, TextFieldError, TextFieldInput, TextFieldLabel } from "@/components/cubix/text-field"

export function TextFieldInvalidDemo() {
  return (
    <TextField className="w-full max-w-sm" invalid>
      <TextFieldLabel>نام کاربری</TextFieldLabel>
      <TextFieldInput dir="ltr" defaultValue="amin!" autoComplete="username" />
      <TextFieldError>فقط حروف انگلیسی، عدد و زیرخط مجاز است.</TextFieldError>
    </TextField>
  )
}

Disabled

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

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

"use client"

import { TextField, TextFieldDescription, TextFieldInput, TextFieldLabel } from "@/components/cubix/text-field"

export function TextFieldDisabledDemo() {
  return (
    <TextField className="w-full max-w-sm" disabled>
      <TextFieldLabel>نام و نام خانوادگی</TextFieldLabel>
      <TextFieldInput defaultValue="امین ابدالی" placeholder="نام کامل" />
      <TextFieldDescription>این فیلد فعلاً قابل ویرایش نیست.</TextFieldDescription>
    </TextField>
  )
}

Sizes

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

نام و نام خانوادگی

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

نام و نام خانوادگی

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

"use client"

import {
  TextField,
  TextFieldClear,
  TextFieldControl,
  TextFieldDescription,
  TextFieldInput,
  TextFieldLabel,
} from "@/components/cubix/text-field"

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

export function TextFieldSizesDemo() {
  return (
    <div className="grid w-full max-w-sm gap-8">
      {sizes.map(({ size, hint }) => (
        <TextField key={size} size={size}>
          <TextFieldLabel>نام و نام خانوادگی</TextFieldLabel>
          <TextFieldControl>
            <Icon data-icon="inline-start" />
            <TextFieldInput placeholder="نام کامل" />
            <TextFieldClear aria-label="پاک کردن" />
          </TextFieldControl>
          <TextFieldDescription>{hint}</TextFieldDescription>
        </TextField>
      ))}
    </div>
  )
}

Icons

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

نام و نام خانوادگی

"use client"

import { TextField, TextFieldControl, TextFieldInput, TextFieldLabel } from "@/components/cubix/text-field"

export function TextFieldIconsDemo() {
  return (
    <TextField className="w-full max-w-sm">
      <TextFieldLabel>نام و نام خانوادگی</TextFieldLabel>
      <TextFieldControl>
        <Icon data-icon="inline-start" />
        <TextFieldInput defaultValue="امین ابدالی" placeholder="نام کامل" />
        <Icon data-icon="inline-end" />
      </TextFieldControl>
    </TextField>
  )
}

Clear

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

جستجو در مخاطبین

"use client"

import {
  TextField,
  TextFieldClear,
  TextFieldControl,
  TextFieldInput,
  TextFieldLabel,
} from "@/components/cubix/text-field"

export function TextFieldClearDemo() {
  return (
    <TextField className="w-full max-w-sm">
      <TextFieldLabel>جستجو در مخاطبین</TextFieldLabel>
      <TextFieldControl>
        <TextFieldInput defaultValue="امین" placeholder="نام مخاطب" />
        <TextFieldClear aria-label="پاک کردن" />
      </TextFieldControl>
    </TextField>
  )
}

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 { Button } from "@/components/cubix/button"
import {
  TextField,
  TextFieldClear,
  TextFieldControl,
  TextFieldDescription,
  TextFieldInput,
  TextFieldLabel,
} from "@/components/cubix/text-field"

export function TextFieldFormDemo() {
  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>
      <TextField name="fullName">
        <TextFieldLabel>نام و نام خانوادگی</TextFieldLabel>
        <TextFieldControl>
          <Icon data-icon="inline-start" />
          <TextFieldInput placeholder="نام کامل" autoComplete="name" required />
          <TextFieldClear aria-label="پاک کردن" />
        </TextFieldControl>
        <TextFieldDescription>همان نامی که در مدارک رسمی ثبت شده است.</TextFieldDescription>
      </TextField>
      <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 { TextField, TextFieldDescription, TextFieldInput, TextFieldLabel } from "@/components/cubix/text-field"

export function TextFieldCustomDemo() {
  return (
    <TextField className="w-full max-w-sm">
      <TextFieldLabel>نام و نام خانوادگی</TextFieldLabel>
      <TextFieldInput
        className="border-border bg-muted focus-visible:bg-background dark:bg-muted dark:focus-visible:bg-background"
        placeholder="نام کامل"
      />
      <TextFieldDescription>با className می‌توانید ظاهر را سفارشی کنید.</TextFieldDescription>
    </TextField>
  )
}

API Reference

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

TextField

Prop	Type	Default	Description
size	"default" \| "lg"	"default"	Height for the input: default 40px, lg 48px. Inherited by TextFieldInput and TextFieldControl 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 TextFieldError when present.
name	string	-	Identifies the field when a form is submitted. Forwarded to TextFieldInput on every base.
className	string	-	Additional Tailwind classes merged with the root styles (last one wins).

TextFieldControl

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

TextFieldInput

Prop	Type	Default	Description
size	"default" \| "lg"	-	Overrides the size from TextField. Default 40px, lg 48px. Use className for other heights.
placeholder	string	-	Hint text shown when the input is empty.
className	string	-	Additional Tailwind classes merged with the input styles (last one wins).
...props	React.ComponentProps<'input'>	-	Native input attributes (value, onChange, name, required, autoComplete, ...) are forwarded. Prefer specialized field components for email, phone, password, and similar inputs.

TextFieldClear

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

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