Amount Field

Web/Mobile

A labeled amount field with currency unit, description, and error. Values always display as Persian digits with thousand separators.

Base UI React Aria Radix UI

Registry API Reference

مبلغ

تومان

مبلغ را به تومان وارد کنید. ارقام به‌صورت خودکار گروه‌بندی می‌شوند.

"use client"

import {
  AmountField,
  AmountFieldControl,
  AmountFieldCurrency,
  AmountFieldDescription,
  AmountFieldInput,
  AmountFieldLabel,
} from "@/components/cubix/amount-field"

export function AmountFieldDemo() {
  return (
    <AmountField className="w-full max-w-sm">
      <AmountFieldLabel>مبلغ</AmountFieldLabel>
      <AmountFieldControl>
        <Icon data-icon="inline-start" />
        <AmountFieldInput defaultValue="۱۲۵۰۰۰۰" placeholder="۰" />
        <AmountFieldCurrency unit="تومان" />
      </AmountFieldControl>
      <AmountFieldDescription>
        مبلغ را به تومان وارد کنید. ارقام به‌صورت خودکار گروه‌بندی می‌شوند.
      </AmountFieldDescription>
    </AmountField>
  )
}

Installation

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

Usage

Import

import {
  AmountField,
  AmountFieldControl,
  AmountFieldCurrency,
  AmountFieldDescription,
  AmountFieldInput,
  AmountFieldLabel,
} from "@/components/cubix/amount-field"

Example

<AmountField className="w-full max-w-sm">
  <AmountFieldLabel>مبلغ</AmountFieldLabel>
  <AmountFieldControl>
    <Icon data-icon="inline-start" />
    <AmountFieldInput defaultValue="۱۲۵۰۰۰۰" placeholder="۰" />
    <AmountFieldCurrency unit="تومان" />
  </AmountFieldControl>
  <AmountFieldDescription>
    مبلغ را به تومان وارد کنید. ارقام به‌صورت خودکار گروه‌بندی می‌شوند.
  </AmountFieldDescription>
</AmountField>

Composition

Same composition as Text Field, with AmountFieldCurrency for the unit.AmountFieldInput uses inputMode="numeric" with type="text", converts Latin digits, and inserts thousand separators as you type. Use parseAmountFieldValue when you need the numeric amount from the formatted string.

Structure

AmountField
├── AmountFieldLabel
├── AmountFieldControl
│   ├── Icon data-icon="inline-start" | "inline-end"
│   ├── AmountFieldInput
│   └── AmountFieldCurrency
├── AmountFieldDescription
└── AmountFieldError

Accessibility

Letters are blocked on insert and paste so the field stays numeric. AmountFieldDescription and AmountFieldError are announced through aria-describedby, and invalid sets aria-invalid on the input. When amountInWords is on, the spoken amount updates as the value changes.

Examples

Description

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

مبلغفقط عدد وارد کنید. جداکننده هزارگان به‌صورت خودکار اضافه می‌شود.

"use client"

import {
  AmountField,
  AmountFieldDescription,
  AmountFieldInput,
  AmountFieldLabel,
} from "@/components/cubix/amount-field"

export function AmountFieldDescriptionDemo() {
  return (
    <AmountField className="w-full max-w-sm">
      <AmountFieldLabel>مبلغ</AmountFieldLabel>
      <AmountFieldInput placeholder="۰" />
      <AmountFieldDescription>
        فقط عدد وارد کنید. جداکننده هزارگان به‌صورت خودکار اضافه می‌شود.
      </AmountFieldDescription>
    </AmountField>
  )
}

Amount in words

Set amountInWords on AmountFieldDescription to spell the amount in Persian. With تومان, words use ریال (×10); with ریال, words use تومان (÷10).

مبلغ

تومان

مبلغ

ریال

"use client"

import {
  AmountField,
  AmountFieldControl,
  AmountFieldCurrency,
  AmountFieldDescription,
  AmountFieldInput,
  AmountFieldLabel,
} from "@/components/cubix/amount-field"

export function AmountFieldAmountInWordsDemo() {
  return (
    <div className="grid w-full max-w-sm gap-8">
      <AmountField>
        <AmountFieldLabel>مبلغ</AmountFieldLabel>
        <AmountFieldControl>
          <AmountFieldInput defaultValue="۱۲۵۰۰۰" placeholder="۰" />
          <AmountFieldCurrency unit="تومان" />
        </AmountFieldControl>
        <AmountFieldDescription amountInWords />
      </AmountField>
      <AmountField>
        <AmountFieldLabel>مبلغ</AmountFieldLabel>
        <AmountFieldControl>
          <AmountFieldInput defaultValue="۱۲۵۰۰۰۰" placeholder="۰" />
          <AmountFieldCurrency unit="ریال" />
        </AmountFieldControl>
        <AmountFieldDescription amountInWords />
      </AmountField>
    </div>
  )
}

Currency

Place AmountFieldCurrency in the control with unit set to تومان or ریال.

مبلغ

تومان

مبلغ

ریال

"use client"

import {
  AmountField,
  AmountFieldControl,
  AmountFieldCurrency,
  AmountFieldInput,
  AmountFieldLabel,
} from "@/components/cubix/amount-field"

export function AmountFieldCurrencyDemo() {
  return (
    <div className="grid w-full max-w-sm gap-8">
      <AmountField>
        <AmountFieldLabel>مبلغ</AmountFieldLabel>
        <AmountFieldControl>
          <AmountFieldInput defaultValue="۲۵۰۰۰۰" placeholder="۰" />
          <AmountFieldCurrency unit="تومان" />
        </AmountFieldControl>
      </AmountField>
      <AmountField>
        <AmountFieldLabel>مبلغ</AmountFieldLabel>
        <AmountFieldControl>
          <AmountFieldInput defaultValue="۲۵۰۰۰۰۰" placeholder="۰" />
          <AmountFieldCurrency unit="ریال" />
        </AmountFieldControl>
      </AmountField>
    </div>
  )
}

Invalid

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

مبلغ

تومان

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

"use client"

import {
  AmountField,
  AmountFieldControl,
  AmountFieldCurrency,
  AmountFieldError,
  AmountFieldInput,
  AmountFieldLabel,
} from "@/components/cubix/amount-field"

export function AmountFieldInvalidDemo() {
  return (
    <AmountField className="w-full max-w-sm" invalid>
      <AmountFieldLabel>مبلغ</AmountFieldLabel>
      <AmountFieldControl>
        <AmountFieldInput defaultValue="۰" placeholder="۰" />
        <AmountFieldCurrency unit="تومان" />
      </AmountFieldControl>
      <AmountFieldError>یک مبلغ معتبر وارد کنید.</AmountFieldError>
    </AmountField>
  )
}

Disabled

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

مبلغ

تومان

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

"use client"

import {
  AmountField,
  AmountFieldControl,
  AmountFieldCurrency,
  AmountFieldDescription,
  AmountFieldInput,
  AmountFieldLabel,
} from "@/components/cubix/amount-field"

export function AmountFieldDisabledDemo() {
  return (
    <AmountField className="w-full max-w-sm" disabled>
      <AmountFieldLabel>مبلغ</AmountFieldLabel>
      <AmountFieldControl>
        <Icon data-icon="inline-start" />
        <AmountFieldInput defaultValue="۱۲۵۰۰۰۰" placeholder="۰" />
        <AmountFieldCurrency unit="تومان" />
      </AmountFieldControl>
      <AmountFieldDescription>این فیلد فعلاً قابل ویرایش نیست.</AmountFieldDescription>
    </AmountField>
  )
}

Sizes

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

مبلغ

تومان

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

مبلغ

تومان

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

"use client"

import {
  AmountField,
  AmountFieldControl,
  AmountFieldCurrency,
  AmountFieldDescription,
  AmountFieldInput,
  AmountFieldLabel,
} from "@/components/cubix/amount-field"

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

export function AmountFieldSizesDemo() {
  return (
    <div className="grid w-full max-w-sm gap-8">
      {sizes.map(({ size, hint }) => (
        <AmountField key={size} size={size}>
          <AmountFieldLabel>مبلغ</AmountFieldLabel>
          <AmountFieldControl>
            <Icon data-icon="inline-start" />
            <AmountFieldInput placeholder="۰" />
            <AmountFieldCurrency unit="تومان" />
          </AmountFieldControl>
          <AmountFieldDescription>{hint}</AmountFieldDescription>
        </AmountField>
      ))}
    </div>
  )
}

Icons

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

موجودی کیف پول

تومان

"use client"

import {
  AmountField,
  AmountFieldControl,
  AmountFieldCurrency,
  AmountFieldInput,
  AmountFieldLabel,
} from "@/components/cubix/amount-field"

export function AmountFieldIconsDemo() {
  return (
    <AmountField className="w-full max-w-sm">
      <AmountFieldLabel>موجودی کیف پول</AmountFieldLabel>
      <AmountFieldControl>
        <Icon data-icon="inline-start" />
        <AmountFieldInput placeholder="۰" />
        <AmountFieldCurrency unit="تومان" />
      </AmountFieldControl>
    </AmountField>
  )
}

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 {
  AmountField,
  AmountFieldControl,
  AmountFieldCurrency,
  AmountFieldDescription,
  AmountFieldInput,
  AmountFieldLabel,
} from "@/components/cubix/amount-field"

export function AmountFieldFormDemo() {
  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>
      <AmountField name="amount">
        <AmountFieldLabel>مبلغ</AmountFieldLabel>
        <AmountFieldControl>
          <Icon data-icon="inline-start" />
          <AmountFieldInput placeholder="۰" required />
          <AmountFieldCurrency unit="تومان" />
        </AmountFieldControl>
        <AmountFieldDescription>یک مبلغ معتبر به تومان وارد کنید.</AmountFieldDescription>
      </AmountField>
      <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 field uses a filled surface instead of the default outline.

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

"use client"

import {
  AmountField,
  AmountFieldDescription,
  AmountFieldInput,
  AmountFieldLabel,
} from "@/components/cubix/amount-field"

export function AmountFieldCustomDemo() {
  return (
    <AmountField className="w-full max-w-sm">
      <AmountFieldLabel>مبلغ</AmountFieldLabel>
      <AmountFieldInput
        className="border-border bg-muted focus-visible:bg-background dark:bg-muted dark:focus-visible:bg-background"
        placeholder="۰"
      />
      <AmountFieldDescription>با className می‌توانید ظاهر را سفارشی کنید.</AmountFieldDescription>
    </AmountField>
  )
}

API Reference

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

AmountField

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

AmountFieldControl

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

AmountFieldInput

Prop	Type	Default	Description
type	"text"	"text"	Always displays Persian digits (۰-۹) with thousand separators (٬). Latin digits typed or pasted are converted. Letters are blocked. inputMode is always numeric and spellCheck is always false.
size	"default" \| "lg"	-	Overrides the size from AmountField. Default 40px, lg 48px. Use className for other heights.
inputMode	"numeric"	"numeric"	Locked to numeric so mobile keyboards show a number pad.
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 amount entry. Use parseAmountFieldValue to read a numeric amount from the formatted string.

AmountFieldCurrency

Prop	Type	Default	Description
unit	"تومان" \| "ریال"	-	Currency label beside the amount. Only تومان or ریال.
className	string	-	Additional Tailwind classes merged with the currency styles (last one wins).

AmountFieldLabel / Description / Error

Prop	Type	Default	Description
amountInWords	boolean	false	On AmountFieldDescription only. When true, spells the entered amount in Persian words. If the currency is تومان, words use ریال (×10); if ریال, words use تومان (÷10). When the input is empty, children are shown instead (or the description hides if there are none). Leave false for a normal static help text.
className	string	-	Additional Tailwind classes merged with the part styles (last one wins).
...props	HTML attributes	-	Native attributes for the rendered element are forwarded.