Skip to main content

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';
Loading…
<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.

Loading…
<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.

Props
min
max
step
design
<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.

Loading…
<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​

Props
showValue
step
design
<Stepper
accessibilityLabel="Guests"
min={0}
max={10}
value={guests}
onValueChange={setGuests}
/>

Designs​

DesignNumberFieldStepper
brand− before the number, + afteran outlined pill with the value between 44pt buttons
iOSa − | + pair after the numberUIStepper: a gray 94×32 track split by a hairline, without the value
Material 3− before, + after, in an outlined fieldtwo tonal round icon buttons around the value
websmall up and down chevrons, as a browser's number inputa compact outlined group

Accessibility​

  • NumberField's input is a spinbutton with its value, min and max, 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.

PropTypeDefaultDescription
valuenumber | null—Controlled value; null is empty.
defaultValuenumber | nullnullInitial value when uncontrolled.
onValueChange(value: number | null) => void—Called on a step, or on blur or Enter after typing.
min, maxnumberno limitThe range.
stepnumber1How much a button or arrow key moves it; also the decimals kept.
formatValue(value: number) => stringStringThe text while not editing.
hideButtonsbooleanfalseHides − and +.
stepLabels{ decrement, increment }'Decrease', 'Increase'The buttons' names for screen readers.

Stepper​

PropTypeDefaultDescription
valuenumber—Controlled value.
defaultValuenumbermin, or 0Initial value when uncontrolled.
onValueChange(value: number) => void—Called when the user steps.
min, maxnumberno limitThe range.
stepnumber1How much one press moves it.
showValuebooleanthe design'sDraws the value between the buttons (all but iOS).
formatValue(value: number) => stringStringThe value as text, shown and read aloud.
accessibilityLabelstring—Names it for screen readers, e.g. 'Guests'.
disabledbooleanfalseDims it and blocks steps.
labels{ decrement, increment }'Decrease', 'Increase'The buttons' names.
style, theme, designAs every component.