Number Field

Web/Mobile

A labeled number field with icons, stepper arrows, description, and error. inputMode is locked to numeric; values always display as Persian digits.

Base UI React Aria Radix UI

Registry API Reference

تعداد

فقط عدد وارد کنید. با فلش‌ها مقدار را کم یا زیاد کنید.

"use client"

import {
  NumberField,
  NumberFieldControl,
  NumberFieldDescription,
  NumberFieldInput,
  NumberFieldLabel,
  NumberFieldStepper,
} from "@/components/cubix/number-field"

export function NumberFieldDemo() {
  return (
    <NumberField className="w-full max-w-sm">
      <NumberFieldLabel>تعداد</NumberFieldLabel>
      <NumberFieldControl>
        <Icon data-icon="inline-start" />
        <NumberFieldInput defaultValue="۱۲" placeholder="۰" />
        <NumberFieldStepper />
      </NumberFieldControl>
      <NumberFieldDescription>
        فقط عدد وارد کنید. با فلش‌ها مقدار را کم یا زیاد کنید.
      </NumberFieldDescription>
    </NumberField>
  )
}

Installation

pnpm dlx cubix-ui@latest add number-field

Usage

Import

import {
  NumberField,
  NumberFieldControl,
  NumberFieldDescription,
  NumberFieldInput,
  NumberFieldLabel,
  NumberFieldStepper,
} from "@/components/cubix/number-field"

Example

<NumberField className="w-full max-w-sm">
  <NumberFieldLabel>تعداد</NumberFieldLabel>
  <NumberFieldControl>
    <Icon data-icon="inline-start" />
    <NumberFieldInput defaultValue="۱۲" placeholder="۰" />
    <NumberFieldStepper />
  </NumberFieldControl>
  <NumberFieldDescription>
    فقط عدد وارد کنید. با فلش‌ها مقدار را کم یا زیاد کنید.
  </NumberFieldDescription>
</NumberField>

Composition

Same composition as Text Field. Place NumberFieldStepper inside the control for up and down arrows that change the value. NumberFieldInput uses inputMode="numeric" with type="text" so values always display as Persian digits; Latin and Arabic-Indic digits are converted as they are typed or pasted.

Structure

NumberField
├── NumberFieldLabel
├── NumberFieldControl
│   ├── Icon data-icon="inline-start" | "inline-end"
│   ├── NumberFieldInput
│   └── NumberFieldStepper
├── NumberFieldDescription
└── NumberFieldError

Accessibility

ArrowUp and ArrowDown on the input step the value by step and respect min and max, so the stepper buttons stay out of the tab order without losing keyboard access. The buttons are named by incrementLabel and decrementLabel. NumberFieldDescription and NumberFieldError are announced through aria-describedby.

Examples

Stepper

NumberFieldStepper renders up and down arrows that increase or decrease the value. Set min, max, and step on the input to bound both the arrows and the keyboard.

تعداد مهمان

بین ۱ تا ۱۰ نفر.

"use client"

import {
  NumberField,
  NumberFieldControl,
  NumberFieldDescription,
  NumberFieldInput,
  NumberFieldLabel,
  NumberFieldStepper,
} from "@/components/cubix/number-field"

export function NumberFieldStepperDemo() {
  return (
    <NumberField className="w-full max-w-sm">
      <NumberFieldLabel>تعداد مهمان</NumberFieldLabel>
      <NumberFieldControl>
        <Icon data-icon="inline-start" />
        <NumberFieldInput defaultValue="۲" min={1} max={10} placeholder="۱" />
        <NumberFieldStepper />
      </NumberFieldControl>
      <NumberFieldDescription>بین ۱ تا ۱۰ نفر.</NumberFieldDescription>
    </NumberField>
  )
}

Description

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

تعداد

مقدار باید یک عدد صحیح باشد.

"use client"

import {
  NumberField,
  NumberFieldDescription,
  NumberFieldInput,
  NumberFieldLabel,
} from "@/components/cubix/number-field"

export function NumberFieldDescriptionDemo() {
  return (
    <NumberField className="w-full max-w-sm">
      <NumberFieldLabel>تعداد</NumberFieldLabel>
      <NumberFieldInput placeholder="۰" />
      <NumberFieldDescription>مقدار باید یک عدد صحیح باشد.</NumberFieldDescription>
    </NumberField>
  )
}

Invalid

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

تعداد

تعداد باید حداقل ۱ باشد.

"use client"

import {
  NumberField,
  NumberFieldControl,
  NumberFieldError,
  NumberFieldInput,
  NumberFieldLabel,
  NumberFieldStepper,
} from "@/components/cubix/number-field"

export function NumberFieldInvalidDemo() {
  return (
    <NumberField className="w-full max-w-sm" invalid>
      <NumberFieldLabel>تعداد</NumberFieldLabel>
      <NumberFieldControl>
        <NumberFieldInput defaultValue="۰" placeholder="۰" />
        <NumberFieldStepper />
      </NumberFieldControl>
      <NumberFieldError>تعداد باید حداقل ۱ باشد.</NumberFieldError>
    </NumberField>
  )
}

Disabled

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

تعداد

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

"use client"

import {
  NumberField,
  NumberFieldControl,
  NumberFieldDescription,
  NumberFieldInput,
  NumberFieldLabel,
  NumberFieldStepper,
} from "@/components/cubix/number-field"

export function NumberFieldDisabledDemo() {
  return (
    <NumberField className="w-full max-w-sm" disabled>
      <NumberFieldLabel>تعداد</NumberFieldLabel>
      <NumberFieldControl>
        <Icon data-icon="inline-start" />
        <NumberFieldInput defaultValue="۱۲" placeholder="۰" />
        <NumberFieldStepper />
      </NumberFieldControl>
      <NumberFieldDescription>این فیلد فعلاً قابل ویرایش نیست.</NumberFieldDescription>
    </NumberField>
  )
}

Sizes

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

تعداد

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

تعداد

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

"use client"

import {
  NumberField,
  NumberFieldControl,
  NumberFieldDescription,
  NumberFieldInput,
  NumberFieldLabel,
  NumberFieldStepper,
} from "@/components/cubix/number-field"

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

export function NumberFieldSizesDemo() {
  return (
    <div className="grid w-full max-w-sm gap-8">
      {sizes.map(({ size, hint }) => (
        <NumberField key={size} size={size}>
          <NumberFieldLabel>تعداد</NumberFieldLabel>
          <NumberFieldControl>
            <Icon data-icon="inline-start" />
            <NumberFieldInput placeholder="۰" />
            <NumberFieldStepper />
          </NumberFieldControl>
          <NumberFieldDescription>{hint}</NumberFieldDescription>
        </NumberField>
      ))}
    </div>
  )
}

Icons

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

موجودی انبار

"use client"

import {
  NumberField,
  NumberFieldControl,
  NumberFieldInput,
  NumberFieldLabel,
  NumberFieldStepper,
} from "@/components/cubix/number-field"

export function NumberFieldIconsDemo() {
  return (
    <NumberField className="w-full max-w-sm">
      <NumberFieldLabel>موجودی انبار</NumberFieldLabel>
      <NumberFieldControl>
        <Icon data-icon="inline-start" />
        <NumberFieldInput placeholder="۰" />
        <NumberFieldStepper />
      </NumberFieldControl>
    </NumberField>
  )
}

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 {
  NumberField,
  NumberFieldControl,
  NumberFieldDescription,
  NumberFieldInput,
  NumberFieldLabel,
  NumberFieldStepper,
} from "@/components/cubix/number-field"

export function NumberFieldFormDemo() {
  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>
      <NumberField name="quantity">
        <NumberFieldLabel>تعداد</NumberFieldLabel>
        <NumberFieldControl>
          <Icon data-icon="inline-start" />
          <NumberFieldInput min={1} placeholder="۱" required />
          <NumberFieldStepper />
        </NumberFieldControl>
        <NumberFieldDescription>حداقل ۱ عدد.</NumberFieldDescription>
      </NumberField>
      <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 {
  NumberField,
  NumberFieldDescription,
  NumberFieldInput,
  NumberFieldLabel,
} from "@/components/cubix/number-field"

export function NumberFieldCustomDemo() {
  return (
    <NumberField className="w-full max-w-sm">
      <NumberFieldLabel>تعداد</NumberFieldLabel>
      <NumberFieldInput
        className="border-border bg-muted focus-visible:bg-background dark:bg-muted dark:focus-visible:bg-background"
        placeholder="۰"
      />
      <NumberFieldDescription>با className می‌توانید ظاهر را سفارشی کنید.</NumberFieldDescription>
    </NumberField>
  )
}

API Reference

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

NumberField

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

NumberFieldControl

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

NumberFieldInput

Prop	Type	Default	Description
type	"text"	"text"	Always displays Persian digits (۰-۹). Latin or Arabic-Indic digits typed or pasted are converted. inputMode is always numeric and spellCheck is always false.
size	"default" \| "lg"	-	Overrides the size from NumberField. Default 40px, lg 48px. Use className for other heights.
inputMode	"numeric"	"numeric"	Locked to numeric so mobile keyboards show a number pad.
min	number \| string	-	Minimum value used by NumberFieldStepper when decreasing.
max	number \| string	-	Maximum value used by NumberFieldStepper when increasing.
step	number \| string	1	Step size used by ArrowUp / ArrowDown on the input and by NumberFieldStepper unless the stepper overrides it.
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 numeric entry.

NumberFieldStepper

Prop	Type	Default	Description
step	number	-	Overrides the input step attribute for the arrow buttons only. Set step on NumberFieldInput to keep keyboard and buttons in sync. Defaults to 1 when neither is set.
incrementLabel	string	"افزایش"	Accessible name for the increase button.
decrementLabel	string	"کاهش"	Accessible name for the decrease button.
className	string	-	Additional Tailwind classes merged with the stepper styles (last one wins).

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