Skip to main content

NumberInput

Edit a constrained number with step buttons and keyboard controls.

Props
Slots

Anatomy#

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 when free-form numeric text is required, and Slider when the value is chosen spatially.

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.

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

<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
↑ Increments the value by step.
↓ Decrements the value by step.
⇞ Increments by largeStep (defaults to step * 10).
⇟ Decrements by largeStep (defaults to step * 10).
↖ Sets the value to min when min is set.
↘ Sets the value to max when max is set.
↵ 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.

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.

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.

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.

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
data-disabled
Slot: number-inputnumber-input-inputnumber-input-incrementnumber-input-decrement
Description: Present when the component, slot, or item is disabled.
data-invalid
Slot: number-inputnumber-input-input
Description: Present when the field or form has a validation error.
data-readonly
Slot: number-inputnumber-input-input
Description: Present when the field is in read-only mode.
data-required
Slot: number-inputnumber-input-input
Description: Present when the field input is required.
data-auto-align
Slot: number-input-input
Description: Present when alignment is selected automatically.
data-active
Slot: number-input-incrementnumber-input-decrement
Description: Present when the item or trigger is active.

Props#

Props for the NumberInput component. Renders a <div> element by default.

Prop