Number Input
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
Preview
Mirrored is the same English content laid out right to left: it separates a mirroring bug from a translation one.
Installation
Add the component
npx ritla add number-inputAlso works with shadcn:
npx shadcn@latest add @ritla/number-inputDependencies it brings
@base-ui/react@phosphor-icons/reactOr 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
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.
API reference
NumberInput
| Prop | Type | Default | Description |
|---|---|---|---|
label | ReactNode | None | Figma's Label. |
value / defaultValue | number | None | The numeric value (not the formatted text). |
onValueChange | (value: number | null) => void | None | When the value changes. |
min / max / step | number | step 1 | Bounds and step. |
largeStep | number | step × 10 | The step for Shift + arrow keys: ten steps by default. |
format | Intl.NumberFormatOptions | None | How the value is formatted. |
prefix | ReactNode | None | _Leading content: a currency or unit. |
stepper | boolean | true | Show the minus / plus steppers. |
decrementLabel / incrementLabel | string | None | Stepper names for screen readers. Default: in the page language. |
required / helperText / error / disabled / readOnly | … | None | As 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.
| Key | Action |
|---|---|
| ArrowUpArrowDown | Steps the value up or down. |
| ShiftArrowUp | Ten steps (largeStep). |
| HomeEnd | The 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
numeralsfromRitlaProvider: ١٬٢٣٤ 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.
- Arabic text falling back past the declared font family (measured, declared, or a webfont that failed to load)
- letter-spacing applied to Arabic text (breaks the connected script)
- Unisolated bidi hazards: phones, emails, Latin tokens inside Arabic text
- Clipped text: content wider than its box with overflow hidden and no ellipsis
- Fixed-pixel-width container whose Arabic text exceeds the space