---
title: NumberInput
description: Edit a constrained number with step buttons and keyboard controls.
package: moraine
version: 0.11.0
repository: https://github.com/subframe7536/moraine
---

# NumberInput

> Edit a constrained number with step buttons and keyboard controls.

## Anatomy

```text
NumberInput [component; slot=root]
├── decrement [slot]
├── input [slot]
└── increment [slot]
```

This is the horizontal layout. A vertical layout wraps the buttons in a `controls` slot after the input.

## Usage

Use NumberInput for a numeric field with step controls and constrained committed values. Use a
plain [Input](https://moraine.subf.dev/components/input.md) when free-form numeric text is required, and
[Slider](https://moraine.subf.dev/components/slider.md) when the value is chosen spatially.

```tsx
import { Field, NumberInput } from 'moraine'

export function Example() {
  return (
    <Field label="Quantity">
      <NumberInput min={0} max={10} defaultValue={1} />
    </Field>
  )
}
```

### Values and boundaries

`value`, `defaultValue`, and `onValueChange` all use `number | undefined`. `value={undefined}` keeps
the input uncontrolled. Display text comes from `locale` (default: the provider locale, then
`en-US`) and `formatOptions`, so the value stays a plain number. Clearing the input emits
`undefined`. Typing commits as soon as the text is a complete number; partial text such as `-` waits
for blur or Enter. Committed, stepped, and controlled values are clamped to `min` and `max`.
`onValueChange` does not fire when the value is unchanged. Decimal steps are calculated to avoid
typical floating-point display noise.

```tsx
<NumberInput value={value()} onValueChange={setValue} min={0} max={10} locale="de-DE" />
<NumberInput defaultValue={19.99} locale="de-DE" formatOptions={{ style: 'currency', currency: 'EUR' }} />
```

Set `name` to submit the plain number through a hidden input, and `form` to associate the control
with a `<form>` outside its ancestors.

### Stepping and repeat

The default layout is horizontal: decrement button, input, increment button. With
`orientation="vertical"`, both buttons move into a `controls` wrapper after the input. Either way,
the input stays the `spinbutton` keyboard target. `increment={false}` or `decrement={false}` hides a
button, and `incrementDisabled` or `decrementDisabled` disables it without blocking keyboard or
wheel stepping. A button is also disabled at `max` or `min`.

`step` (default `1`) sets the amount for the buttons, ArrowUp and ArrowDown, and the mouse wheel.
`largeStep` (default `step * 10`) sets the amount for PageUp and PageDown, and for the wheel while
Shift is held. By default stepping lands on the step grid anchored at `min` (or at `0` without
`min`), so `step={5}` from `7` goes to `10`; set `stepSnapping={false}` to step from the exact
value. Typed values are clamped, never snapped. The wheel steps only when `wheel` is set and the
input is focused.

Hold-to-repeat on the buttons is enabled by default. Tune it with
`repeat={{ delay, interval, throttle, pointerTypes }}` (defaults `500`, `80`, `0`, and `'all'`;
`interval` has a floor of 16 ms) or disable it with `repeat={false}`.

```tsx
<NumberInput defaultValue={100} step={5} largeStep={25} />
<NumberInput defaultValue={0.5} step={0.1} min={0} max={1} />
```

### Keyboard interaction

Keys have no effect while the control is disabled or read-only.

| Key                  | Description                                          |
| -------------------- | ---------------------------------------------------- |
| <kbd>ArrowUp</kbd>   | Increments the value by `step`.                      |
| <kbd>ArrowDown</kbd> | Decrements the value by `step`.                      |
| <kbd>PageUp</kbd>    | Increments by `largeStep` (defaults to `step * 10`). |
| <kbd>PageDown</kbd>  | Decrements by `largeStep` (defaults to `step * 10`). |
| <kbd>Home</kbd>      | Sets the value to `min` when `min` is set.           |
| <kbd>End</kbd>       | Sets the value to `max` when `max` is set.           |
| <kbd>Enter</kbd>     | Commits the typed text as a number.                  |

## Examples

### Set a cart quantity

Keep the count in local state with `onValueChange`. Bound it with `min` and `max`.

```tsx
import { Badge, NumberInput } from 'moraine'
import { createSignal } from 'solid-js'

export function Controlled() {
  const [quantity, setQuantity] = createSignal(2)
  const unitPrice = 49.0

  return (
    <div class="p-4 b-1 b-border rounded-xl max-w-md space-y-4">
      <div class="flex items-center justify-between">
        <div>
          <h4 class="text-sm font-medium">Mechanical Keyboard (Pro Edition)</h4>
          <p class="text-xs text-muted-foreground">$49.00 / unit</p>
        </div>
        <Badge variant="outline">In Stock</Badge>
      </div>

      <div class="pt-2 border-t border-border flex items-center justify-between">
        <div class="space-y-1">
          <label class="text-xs text-muted-foreground font-medium">Quantity (Max 10)</label>
          <NumberInput
            value={quantity()}
            onValueChange={(v) => {
              if (v !== undefined) {
                setQuantity(v)
              }
            }}
            min={1}
            max={10}
            step={1}
            variant="outline"
          />
        </div>

        <div class="text-right">
          <p class="text-xs text-muted-foreground">Subtotal</p>
          <p class="text-lg text-primary font-mono font-semibold">
            ${(quantity() * unitPrice).toFixed(2)}
          </p>
        </div>
      </div>
    </div>
  )
}
```

### Edit a retry delay

Use `step` for the arrow keys and `largeStep` for PageUp and PageDown. Home and End jump to the
`min` and `max` bounds.

```tsx
import { NumberInput } from 'moraine'
import { createSignal } from 'solid-js'

export function KeyboardStepping() {
  const [value, setValue] = createSignal(4)

  return (
    <div class="max-w-sm space-y-3">
      <NumberInput
        aria-label="Retry delay in seconds"
        value={value()}
        min={0}
        max={60}
        step={0.5}
        largeStep={5}
        onValueChange={setValue}
      />
      <p class="text-sm text-muted-foreground">Current delay: {value()} seconds</p>
      <p class="text-xs text-muted-foreground">
        Arrow keys change by 0.5, PageUp/PageDown by 5, and Home/End jump to 0 or 60.
      </p>
    </div>
  )
}
```

### Hold to change a count

Hold-to-repeat is on by default. Tune it with `repeat={{ delay, interval, throttle, pointerTypes }}`
or pass `repeat={false}` to step once per click.

```tsx
import { NumberInput } from 'moraine'
import { createSignal } from 'solid-js'

export function LongPress() {
  const [repeatValue, setRepeatValue] = createSignal(12)
  const [singleStepValue, setSingleStepValue] = createSignal(12)

  return (
    <div class="max-w-xs space-y-4">
      <div class="space-y-2">
        <NumberInput
          value={repeatValue()}
          onValueChange={(value) => {
            if (value !== undefined) {
              setRepeatValue(value)
            }
          }}
          min={0}
          max={99}
          step={1}
          variant="subtle"
        />
        <p class="text-xs text-muted-foreground">
          Hold <span class="font-medium">+</span> or <span class="font-medium">−</span> to repeat.
          Current value: {repeatValue()}
        </p>
      </div>

      <div class="space-y-2">
        <NumberInput
          value={singleStepValue()}
          repeat={false}
          onValueChange={(value) => {
            if (value !== undefined) {
              setSingleStepValue(value)
            }
          }}
          min={0}
          max={99}
          step={1}
          variant="subtle"
        />
        <p class="text-xs text-muted-foreground">
          Set <code>repeat=false</code> to keep press-and-hold at a single step. Current value:{' '}
          {singleStepValue()}
        </p>
      </div>
    </div>
  )
}
```

### Bind a numeric field

Place NumberInput in `form.Field` so the schema owns the committed number.

```tsx
import { Button, createForm, NumberInput } from 'moraine'
import { createSignal } from 'solid-js'
import * as v from 'valibot'

export function FormIntegration() {
  const [submittedQuantity, setSubmittedQuantity] = createSignal<number | null>(null)
  const form = createForm({
    schema: v.object({
      quantity: v.pipe(
        v.number('Please enter a number'),
        v.minValue(1, 'Quantity must be at least 1 item.'),
        v.maxValue(10, 'Maximum order quantity is 10 items.'),
      ),
    }),
    initialInput: { quantity: 1 },
    validate: 'input',
  })

  return (
    <form.Form onSubmit={(output) => setSubmittedQuantity(output.quantity)}>
      <div class="max-w-xl space-y-4">
        <form.Field
          name="quantity"
          label="Order Quantity"
          description="Specify between 1 and 10 units."
          required
        >
          <NumberInput min={1} max={10} />
        </form.Field>
        <div class="flex gap-3 items-center">
          <Button type="submit" variant="soft" tone="neutral" size="sm">
            Validate
          </Button>
          <p class="text-xs text-muted-foreground">Selected units: {submittedQuantity() ?? 1}</p>
        </div>
      </div>
    </form.Form>
  )
}
```

## API Reference

### Attributes

| Attributes | Slot | Description |
| --- | --- | --- |
| `data-disabled` | `number-input`, `number-input-input`, `number-input-increment`, `number-input-decrement` | Present when the component, slot, or item is disabled. |
| `data-invalid` | `number-input`, `number-input-input` | Present when the field or form has a validation error. |
| `data-readonly` | `number-input`, `number-input-input` | Present when the field is in read-only mode. |
| `data-required` | `number-input`, `number-input-input` | Present when the field input is required. |
| `data-auto-align` | `number-input-input` | Present when alignment is selected automatically. |
| `data-active` | `number-input-increment`, `number-input-decrement` | Present when the item or trigger is active. |

### Props

Props for the NumberInput component.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| align | 'start' \| 'center' \| 'end' \| undefined | — | Text alignment; omitted values follow the control layout. |
| autofocus | boolean \| undefined | false | Whether the input is focused after mounting, by script rather than the native `autofocus`<br>attribute. Focus is skipped when the control is disabled, and `autofocusDelay` postpones it. |
| autofocusDelay | number \| undefined | 0 | Delay in milliseconds between mount and focusing the input. Only used with `autofocus`. |
| decrement | boolean \| undefined | true | Whether to render the decrement button. The button is also disabled automatically at `min`. |
| decrementDisabled | boolean \| undefined | — | Whether the decrement button is disabled. Keyboard and wheel stepping stay available. |
| decrementIcon | IconT.Name \| undefined | orientation === 'vertical' ? 'icon-chevron-down' : 'icon-minus' | Icon for the decrement button. |
| defaultValue | number \| undefined | — | Default numeric value for uncontrolled usage. `undefined` starts empty. |
| disabled | boolean \| undefined | false | Whether the control is disabled: it cannot be interacted with and sets `aria-disabled`.<br>When omitted, the control inherits `disabled` from the surrounding `Field`; an explicit<br>`false` overrides the `Field`. |
| form | string \| undefined | — | The `id` of the `<form>` the control belongs to, for a control rendered outside that form.<br>It is set on the visible input and on the hidden input that submits the value under `name`. |
| formatOptions | Intl.NumberFormatOptions \| undefined | — | `Intl.NumberFormat` options for display formatting and parsing. The value stays a plain<br>number; only the displayed text is formatted. |
| id | string \| undefined | — | The ID of the control's main focusable element, which a surrounding `Field` label points to<br>with `for`. A unique ID is generated when omitted. The control's related parts (hidden<br>input, label, description) derive their IDs from it, so keep it unique on the page. |
| increment | boolean \| undefined | true | Whether to render the increment button. The button is also disabled automatically at `max`. |
| incrementDisabled | boolean \| undefined | — | Whether the increment button is disabled. Keyboard and wheel stepping stay available. |
| incrementIcon | IconT.Name \| undefined | orientation === 'vertical' ? 'icon-chevron-up' : 'icon-plus' | Icon for the increment button. |
| inputRef | Ref<HTMLInputElement> \| undefined | — | Ref callback or variable that receives the visible `<input role="spinbutton">` element. |
| largeStep | number \| undefined | step * 10 | Amount added or subtracted by `PageUp` / `PageDown`, and by the wheel while `Shift` is held. |
| locale | string \| undefined | — | Locale for number formatting and parsing as a BCP 47 tag such as `en-US`.<br>Falls back to the provider locale, then `en-US`. |
| max | number \| undefined | — | Maximum allowed value. Typed, stepped, and controlled values are clamped to it and it is<br>exposed as `aria-valuemax`. The `End` key jumps to it. Unbounded by default. |
| min | number \| undefined | — | Minimum allowed value. Typed, stepped, and controlled values are clamped to it; it anchors<br>the step grid and is exposed as `aria-valuemin`. The `Home` key jumps to it. Unbounded by default. |
| name | string \| undefined | — | The name of the control, used for native form submission. When omitted, the control uses<br>the name of its form binding or a string `name` set on the surrounding `Field`. |
| onBlur | JSX.FocusEventHandlerUnion<HTMLInputElement, FocusEvent> \| undefined | — | Called when the input loses focus, before the typed text is committed. Calling<br>`preventDefault` skips that commit and the `Field` blur notification. |
| onDecrement | JSX.EventHandlerUnion<HTMLButtonElement, MouseEvent> \| undefined | — | Called when the decrement button is clicked, or on each step while it is held. On a click,<br>calling `preventDefault` cancels the step; repeated steps receive a synthetic event and<br>cannot be cancelled. |
| onFocus | JSX.FocusEventHandlerUnion<HTMLInputElement, FocusEvent> \| undefined | — | Called when the input gains focus. Calling `preventDefault` skips the `Field` focus notification. |
| onIncrement | JSX.EventHandlerUnion<HTMLButtonElement, MouseEvent> \| undefined | — | Called when the increment button is clicked, or on each step while it is held. On a click,<br>calling `preventDefault` cancels the step; repeated steps receive a synthetic event and<br>cannot be cancelled. |
| onValueChange | ((value: number \| undefined) => void) \| undefined | — | Called when the committed value changes, with the value clamped to `min` / `max`, or<br>`undefined` when the input is cleared. Typing commits as soon as the text is a complete<br>number; partial text such as `-` waits for blur or `Enter`. Not called when the value is unchanged. |
| orientation | 'horizontal' \| 'vertical' \| undefined | 'horizontal' | Visual layout direction. |
| placeholder | string \| undefined | — | Hint text shown in the visible input while it is empty. |
| readOnly | boolean \| undefined | false | Whether the control is read-only: the value is visible and focusable but cannot be changed,<br>and `aria-readonly` is set. When omitted, the control inherits `readOnly` from the<br>surrounding `Field`. |
| repeat | boolean \| RepeatOptions \| undefined | true | Press-and-hold repeat on the step buttons: `true` for the defaults, `false` to step only on<br>click, or an options object. Keyboard and wheel stepping are not affected. |
| required | boolean \| undefined | false | Whether the control is required, which sets `aria-required` (and the native `required`<br>attribute where the control renders a native input). When omitted, the control inherits<br>`required` from the surrounding `Field`. |
| size | 'sm' \| 'md' \| 'lg' \| undefined | 'md' | Visual size of the component. |
| step | number \| undefined | 1 | Amount added or subtracted by the step buttons, `ArrowUp` / `ArrowDown`, and the mouse wheel. |
| stepSnapping | boolean \| undefined | true | Whether stepping (buttons, arrow and `Page` keys, wheel) lands on the step grid anchored at<br>`min`, or at `0` without `min`; for example `step={5}` from `7` goes to `10`. Typed values are<br>only clamped, never snapped. |
| translations | Translations \| undefined | — | Localized message overrides for this number input instance: `increment` and `decrement` are<br>the `aria-label`s of the step buttons. |
| value | number \| undefined | — | Controlled numeric value. `undefined` keeps the input uncontrolled, and setting it back to<br>`undefined` clears the displayed text. The displayed value is clamped to `min` / `max`; update<br>it from `onValueChange`. |
| variant | 'outline' \| 'subtle' \| 'ghost' \| 'none' \| undefined | 'outline' | Visual treatment of the component. |
| wheel | boolean \| undefined | false | Whether scrolling the mouse wheel over the focused input steps the value: up increments,<br>down decrements, and holding `Shift` uses `largeStep`. The page does not scroll while it<br>steps; `Ctrl` + wheel (zoom) is ignored. |
| class | SlotClassValue \| undefined | — | Class applied to the component root or trigger element. |
| classes | Classes \| undefined | — | Family slot class defaults for this instance. |
| style | SlotStyleValue \| undefined | — | Style applied to the component root or trigger element. |
| styles | Styles \| undefined | — | Family slot style defaults for this instance. |

**`formatOptions` example**

```tsx
import { NumberInput } from 'moraine'

<NumberInput
  defaultValue={19.99}
  locale="de-DE"
  formatOptions={{ style: 'currency', currency: 'EUR' }}
/>
```

**`repeat` example**

```tsx
import { NumberInput } from 'moraine'

<NumberInput repeat={{ delay: 300, interval: 50, pointerTypes: 'mouse' }} />
```
