# React Native NumberField and Stepper

> Accessible React Native number inputs for iOS, Android and the web: NumberField with − and + buttons, min, max, decimal steps and formatting, and a Stepper drawn as iOS's UIStepper, Material 3 tonal buttons or a web control. Hold to repeat.

# 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.

```tsx
import { NumberField, Stepper } from 'patine-ui';
```

```tsx live
import { Box, HStack, NumberField, Separator, Stepper, Text, VStack } from 'patine-ui';

export default function Example() {
  const [adults, setAdults] = React.useState(2);
  const [children, setChildren] = React.useState(0);
  const [budget, setBudget] = React.useState(180);
  const nights = 3;
  return (
    <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.

```tsx live
import { useState } from 'react';
import { Box, HStack, NumberField, Text } from 'patine-ui';

const COST = 21.4;

export default function Example() {
  const [price, setPrice] = useState<number | null>(49);
  const [discount, setDiscount] = useState<number | null>(15);
  const sale = (price ?? 0) * (1 - (discount ?? 0) / 100);
  const margin = sale ? ((sale - COST) / sale) * 100 : 0;
  return (
    <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.

`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](./text-field) props work the same.

```tsx live
import { NumberField, VStack } from 'patine-ui';

export default function Example() {
  return (
    <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>
  );
}
```

## 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 `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](./text-field)'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. |
