Number Field

Usage

import { NumberField } from '@appica/ui-react/number-field'

<NumberField defaultValue={1} min={0} max={10} />

NumberField folds the decrement button, text input, and increment button into one control — you render a single <NumberField />, not a set of parts. It accepts only numeric input, steps with the buttons or the ↑/↓ arrow keys, and reformats the value when you commit. Use it uncontrolled with defaultValue, or controlled with value + onValueChange.

Unlike a checkbox or radio, the input is a real text field, so give it a label the usual way — an external <label htmlFor> pointing at the field's id, or an aria-label. The rolling-digit animation on stepper presses is skipped when the user prefers reduced motion.

Examples

Variants

variant switches the appearance between a bordered outline (default) and a filled soft field. The stepper buttons invert their fill so they stay legible against either.

import { NumberField } from '@appica/ui-react/number-field'

export default function NumberFieldVariants() {
  return (
    <div className="flex flex-wrap items-center gap-6">
      <NumberField variant="outline" defaultValue={3} aria-label="Outline quantity" />
      <NumberField variant="soft" defaultValue={3} aria-label="Soft quantity" />
    </div>
  )
}

Sizes

size scales the field width, steppers, and text together — sm, md (default), or lg.

import { NumberField } from '@appica/ui-react/number-field'

export default function NumberFieldSizes() {
  return (
    <div className="flex flex-wrap items-center gap-6">
      <NumberField size="sm" defaultValue={3} aria-label="Small quantity" />
      <NumberField size="md" defaultValue={3} aria-label="Medium quantity" />
      <NumberField size="lg" defaultValue={3} aria-label="Large quantity" />
    </div>
  )
}

Min, max & step

min and max clamp the value and disable the stepper once a bound is reached; clearing the field and blurring snaps back to min (or 0). step sets how far each press or arrow key moves the value — hold Shift for largeStep (10× by default) or Alt for smallStep.

import { Field, FieldLabel } from '@appica/ui-react/field'
import { NumberField } from '@appica/ui-react/number-field'

export default function NumberFieldMinMaxStep() {
  return (
    <Field>
      <FieldLabel className="mb-2">Rating (0-20, step 1)</FieldLabel>
      <NumberField defaultValue={5} min={0} max={20} step={1} />
    </Field>
  )
}

Formatting

Pass format — an Intl.NumberFormatOptions object — and an optional locale to display the value as currency, a percentage, units, and the like. The display reformats while the underlying value stays a plain number.

import { NumberField } from '@appica/ui-react/number-field'

export default function NumberFieldFormatting() {
  return (
    <div className="flex flex-wrap items-end gap-6">
      <div className="flex flex-col gap-1.5">
        <label htmlFor="nf-price" className="text-foreground-intense text-sm font-medium">
          Price
        </label>
        <NumberField
          id="nf-price"
          className="w-40"
          defaultValue={19.99}
          step={0.5}
          format={{ style: 'currency', currency: 'USD' }}
          locale="en-US"
        />
      </div>
      <div className="flex flex-col gap-1.5">
        <label htmlFor="nf-rate" className="text-foreground-intense text-sm font-medium">
          Rate
        </label>
        <NumberField
          id="nf-rate"
          className="w-32"
          defaultValue={0.15}
          min={0}
          max={1}
          step={0.01}
          format={{ style: 'percent' }}
        />
      </div>
    </div>
  )
}

Controlled

Drive the value yourself with value + onValueChange. The handler receives null when the field is empty, so coalesce before using the number.

'use client'

import { useState } from 'react'
import { NumberField } from '@appica/ui-react/number-field'

export default function NumberFieldControlled() {
  const [value, setValue] = useState<number | null>(2)
  return (
    <div className="flex flex-col items-center gap-3">
      <NumberField value={value} onValueChange={setValue} min={0} aria-label="Guests" />
      <p className="text-sm">
        {value ?? 0} {value === 1 ? 'guest' : 'guests'}
      </p>
    </div>
  )
}

Disabled & error states

disabled greys out the field and both steppers and blocks interaction. Set aria-invalid to paint the error state — it's mirrored to data-invalid on the field and its steppers. Wrapping the field in a Field marked invalid produces the same styling and is the better choice when you're also rendering a validation message.

import { NumberField } from '@appica/ui-react/number-field'

export default function NumberFieldStates() {
  return (
    <div className="flex flex-wrap items-center gap-6">
      <NumberField variant="soft" defaultValue={3} disabled aria-label="Disabled quantity" />
      <NumberField variant="soft" defaultValue={3} aria-invalid aria-label="Quantity with error" />
    </div>
  )
}

RTL

Every Appica UI component supports right-to-left layouts out of the box. Set the dir attribute on a container (commonly your <html> element) so CSS logical properties resolve correctly, and wrap your tree in DirectionProvider so direction-aware behavior — roving focus, popup placement, and the like — follows the same direction.

import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}

The decrement and increment steppers swap sides to follow the resolved direction, and a matching locale formats the value with that locale's own digits. For setup details and caveats, see the RTL guide.

API reference

A single control. The variant, size, placeholder, and inputProps props are Appica additions; every other prop is forwarded to Base UI's NumberField.Root.

NumberField wraps Base UI's NumberField (Root, Input, Increment, Decrement) and forwards every remaining Root prop. It exposes data-* state attributes (data-disabled, data-readonly, data-invalid, data-scrubbing, …) on the field and its parts for styling — see the Base UI docs for the full surface. When placed inside a Base UI Field.Root marked invalid, the error state (data-invalid) propagates to the input and both steppers automatically.

Accessibility

• The inner element is a real <input> with role="spinbutton", exposing aria-valuenow, aria-valuemin, and aria-valuemax to assistive tech.
• Give the field an accessible name — an external <label htmlFor> pointing at its id, or an aria-label.
• The steppers are real <button>s labelled Increase value / Decrease value, and become disabled at a bound or when the field is disabled.
• ↑/↓ step the value (with Shift/Alt for the large/small step), and typing accepts only valid numeric input.
• disabled blocks all interaction; readOnly keeps the field focusable but inert.
• aria-invalid is bridged to data-invalid so the error state can be styled without a wrapping Field.
• The rolling-digit animation on stepper presses honours prefers-reduced-motion.