Skip to content

Number Input

Get Ritla UI

A number field with minus / plus steppers and an optional currency prefix. It writes the value in the page's numerals (123 or ١٢٣) and accepts either when typed.

Ritla scan of this preview: 40 of 41 checks3 breakpointsScanned Known misread of our own scanner: R023

Open in Figma

Preview

Mirrored is the same English content laid out right to left: it separates a mirroring bug from a translation one.

PreviewCode
EnglishMirroredArabic
LTR →

Installation

  1. Add the component

    npx ritla add number-input

    Also works with shadcn: npx shadcn@latest add @ritla/number-input

  2. Dependencies it brings

    @base-ui/react@phosphor-icons/react

  3. Or copy by hand

    Installing by hand copies the component's source into your project. The source comes with a Ritla UI license, so the CLI is the short way to the same files.

Usage

number-input.tsx
import { NumberInput } from "@/components/ui/number-input";<NumberInput label="Amount" prefix="$" defaultValue={100} min={0} step={50} />

Examples

States and formats

format takes Intl.NumberFormat options (fractions, grouping). Read-only hides the steppers.

EnglishMirroredArabic
LTR →

API reference

NumberInput

PropTypeDefaultDescription
labelReactNodeNoneFigma's Label.
value / defaultValuenumberNoneThe numeric value (not the formatted text).
onValueChange(value: number | null) => voidNoneWhen the value changes.
min / max / stepnumberstep 1Bounds and step.
largeStepnumberstep × 10The step for Shift + arrow keys: ten steps by default.
formatIntl.NumberFormatOptionsNoneHow the value is formatted.
prefixReactNodeNone_Leading content: a currency or unit.
stepperbooleantrueShow the minus / plus steppers.
decrementLabel / incrementLabelstringNoneStepper names for screen readers. Default: in the page language.
required / helperText / error / disabled / readOnly…NoneAs on Input Field.

Usage guidelines

A number input is for money and quantities typed by hand. When to use it, how to state limits and errors, and the checks before handoff.

1. When to use it

For money and quantities typed by hand: transfer amounts, limits and quantities. Use a Slider only for rough values.

Do

  • Show the currency next to the value.
  • Show the balance or the limit under the field.
  • Format with group separators while people type.

Don't

  • Use a plain text field for money.
  • Allow more decimals than the currency has.

2. Limits and errors

Say the rule before people break it, and check it when they stop typing.

Do

  • Use three decimals for JOD and KWD, two for most others.
  • Show the limit as helper text.

Don't

  • Use a spinner for amounts.
  • Show an error before the person finishes typing.

3. Arabic and RTL

The field mirrors and the currency sits at the reading end. Digits stay Latin and left to right.

Accessibility

Keyboard

Keys are written for left-to-right. In right-to-left the arrow keys swap: the one pointing toward the reading direction moves forward.

KeyAction
ArrowUpArrowDownSteps the value up or down.
ShiftArrowUpTen steps (largeStep).
HomeEndThe min and max, when set.

ARIA

  • The input is tied to its label and helper text like Input Field.
  • The steppers are named (“Increase”, “Decrease”) in the page language.

Do

  • inputmode="decimal" on phones.
  • Tie the helper text and the error to the field.

Don't

  • The placeholder as the label.

Arabic and RTL notes

Mirrors

  • The currency sits at the start (the right) and the steppers at the end, plus on the far left.

Does not mirror

  • The number reads left to right (dir="ltr") so a minus sign stays in front, aligned to the start of the field.
Numerals
Follows numerals from RitlaProvider: ١٬٢٣٤ or 1,234. Typed Arabic-Indic and Persian digits are read as numbers.
Arabic typography
label-16, like every field.

Do

  • Accept Arabic-Indic digits from the keyboard and convert them.
  • Use «د.أ» and «ر.س» in Arabic.

Don't

  • Show Arabic-Indic digits unless the whole product does.
  • Move the minus sign away from the number.

Checks it passes

The Ritla checks this component satisfies by construction. Used as documented, it does not bring these defects onto your page.

  • R050Arabic text falling back past the declared font family (measured, declared, or a webfont that failed to load)
  • R051letter-spacing applied to Arabic text (breaks the connected script)
  • R021Unisolated bidi hazards: phones, emails, Latin tokens inside Arabic text
  • R042Clipped text: content wider than its box with overflow hidden and no ellipsis
  • R043Fixed-pixel-width container whose Arabic text exceeds the space