NumberField & Stepper
Two ways to enter a number. NumberField is a text field with − and + buttons, for numbers people type: an age, a price, a weight. Stepper is just the buttons, for small counts people tap: guests, quantity, font size. Both keep the value between min and max, step by step, and keep stepping while a button is held.
import { NumberField, Stepper } from 'patine-ui';
<Box padding="lg" border radius="lg" gap="md" style={{ maxWidth: 380 }}> <Text weight="semibold" size="lg">Who's coming?</Text> <HStack justify="space-between"> <VStack> <Text weight="medium">Adults</Text> <Text size="sm" color="textSecondary">Ages 13 or above</Text> </VStack> <Stepper value={adults} onValueChange={setAdults} min={1} max={8} accessibilityLabel="Adults" /> </HStack> <Separator /> <HStack justify="space-between"> <VStack> <Text weight="medium">Children</Text> <Text size="sm" color="textSecondary">Ages 2–12</Text> </VStack> <Stepper value={children} onValueChange={setChildren} min={0} max={6} accessibilityLabel="Children" /> </HStack> <NumberField label="Budget per night" value={budget} onValueChange={setBudget} min={50} max={1000} step={10} formatValue={(v) => `$${v}`} helperText={`${adults + children} guests · ${nights} nights · $${(budget ?? 0) * nights} total`} /> </Box>
Example: price a product
A store's product editor: the price steps by 50 cents and shows as euros, the discount is a whole percent from 0 to 90, and the margin under them follows both.
<Box border radius="lg" padding="lg" gap="md" style={{ width: '100%', maxWidth: 380 }}> <Text weight="semibold">Linen shirt · cost €{COST.toFixed(2)}</Text> <NumberField label="Price" value={price} onValueChange={setPrice} min={0} step={0.5} formatValue={(v) => `€${v.toFixed(2)}`} /> <NumberField label="Launch discount" value={discount} onValueChange={setDiscount} min={0} max={90} step={5} formatValue={(v) => `${v}%`} helperText={`Customers pay €${sale.toFixed(2)}`} /> <HStack justify="space-between"> <Text color="textSecondary">Margin</Text> <Text weight="semibold" color={margin < 30 ? 'danger' : 'success'}> {margin.toFixed(0)}%{margin < 30 ? ' · below your 30% floor' : ''} </Text> </HStack> </Box>
NumberField
Typing is read when the field loses focus or the user presses Enter, so half-typed text like - or 1. isn't thrown away. A value past min or max is pulled back in, text that isn't a number puts back the last value, and clearing the field gives null. A comma works as the decimal point.
minmaxstepdesign<NumberField
label="Quantity"
value={quantity}
onValueChange={setQuantity}
min={0}
max={10}
/>
formatValue turns the value into the text shown while the field isn't being edited, such as a currency; while editing, the plain number shows. Label, helperText, error, required, prefix, suffix and the other TextField props work the same.
<VStack gap="md" style={{ maxWidth: 320 }}> <NumberField label="Weight" defaultValue={72.5} step={0.5} min={0} suffix="kg" /> <NumberField label="Discount" defaultValue={15} min={0} max={100} suffix="%" error="Discounts above 10% need approval" /> <NumberField label="Seats" defaultValue={4} hideButtons helperText="Arrow keys still step it" /> </VStack>
Stepper
showValuestepdesign<Stepper
accessibilityLabel="Guests"
min={0}
max={10}
value={guests}
onValueChange={setGuests}
/>
Designs
| Design | NumberField | Stepper |
|---|---|---|
| brand | − before the number, + after | an outlined pill with the value between 44pt buttons |
| iOS | a − | + pair after the number | UIStepper: a gray 94×32 track split by a hairline, without the value |
| Material 3 | − before, + after, in an outlined field | two tonal round icon buttons around the value |
| web | small up and down chevrons, as a browser's number input | a compact outlined group |
Accessibility
- NumberField's input is a
spinbuttonwith its value,minandmax, and screen readers' increment and decrement actions. Up and Down arrow keys step it. - Stepper is one adjustable control named by
accessibilityLabel: VoiceOver and TalkBack swipe up and down to change it, and on the web arrow keys, Home and End do. The − and + buttons dim at the ends. - The buttons reach 44pt touch targets on phones. Name them in your language with
stepLabels/labels.
Props
NumberField
Also takes TextField's props, except value, defaultValue, onValueChange, clearable and the password ones.
| Prop | Type | Default | Description |
|---|---|---|---|
value | number | null | — | Controlled value; null is empty. |
defaultValue | number | null | null | Initial value when uncontrolled. |
onValueChange | (value: number | null) => void | — | Called on a step, or on blur or Enter after typing. |
min, max | number | no limit | The range. |
step | number | 1 | How much a button or arrow key moves it; also the decimals kept. |
formatValue | (value: number) => string | String | The text while not editing. |
hideButtons | boolean | false | Hides − and +. |
stepLabels | { decrement, increment } | 'Decrease', 'Increase' | The buttons' names for screen readers. |
Stepper
| Prop | Type | Default | Description |
|---|---|---|---|
value | number | — | Controlled value. |
defaultValue | number | min, or 0 | Initial value when uncontrolled. |
onValueChange | (value: number) => void | — | Called when the user steps. |
min, max | number | no limit | The range. |
step | number | 1 | How much one press moves it. |
showValue | boolean | the design's | Draws the value between the buttons (all but iOS). |
formatValue | (value: number) => string | String | The value as text, shown and read aloud. |
accessibilityLabel | string | — | Names it for screen readers, e.g. 'Guests'. |
disabled | boolean | false | Dims it and blocks steps. |
labels | { decrement, increment } | 'Decrease', 'Increase' | The buttons' names. |
style, theme, design | As every component. |