Number Field

import { NumberField } from "@lumiose/ui"; // or "@lumiose/ui/number-field"
import "@lumiose/ui/number-field.css"; // or "@lumiose/ui/styles.css" for every component
import "@lumiose/ui/themes/default.css"; // optional: the default theme

#Anatomy

<NumberField.Root>
  <NumberField.ScrubArea />
  <NumberField.Group>
    <NumberField.Decrement />
    <NumberField.Input />
    <NumberField.Increment />
  </NumberField.Group>
</NumberField.Root>

Name the field with a Field (Field.Label), a <label for> the Root's id, or an aria-label on the Input.

#API

#NumberField.Root

#NumberField.ScrubArea

#The other parts

Group takes <div> props. Input takes <input> props except the range's own (type, value, min, max, step, name, required, readonly, id: the Root's). Increment and Decrement take <button> props; give them an aria-label in the page's language. Inside a Field, the input takes the field's id, name, description and error.

Native or formatted. A native number input cannot show grouping, a currency or a percentage, and reads a typed number in the browser's own way, so a formatted field is a text field with the spinbutton role, and the number it submits sits in a hidden input. The native input is the default because it needs no JavaScript: typing, the arrow keys, min, max and step validation and the form value are the browser's.

With snapOnStep, each kind of step snaps to its own size: Shift steps 37 up to 40, Alt steps 1.37 up to 1.4. A native field (no format) validates the value against step without JavaScript; the script sets its step to any, so the values Alt's small step, Home, End and clamping give always submit.

The keyboard: inputmode="decimal" when min is 0 or more, "text" otherwise, since iOS's decimal keyboard has no minus sign. Digits of other scripts (full-width １, Arabic-Indic ٤) are read as numbers.

Differences from Base UI's NumberField. No ScrubAreaCursor: Base UI draws a cursor because its scrub area locks the pointer (which hides the real one); this scrub area keeps the real cursor (a resize cursor), so a drag stops at the screen's edge. No inputRef, no render. locale is a string, written to the element for its script.

#Example

import { NumberField } from "@lumiose/ui";
import { signal } from "lumiose";

export function PriceField() {
  const price = signal<number | null>(19.9);
  return (
    <NumberField.Root
      id="price"
      name="price"
      bind:value={price}
      min={0}
      step={0.5}
      format={{ style: "currency", currency: "EUR" }}
      class="lu-number-field"
    >
      <NumberField.ScrubArea>
        <label for="price">Price</label>
      </NumberField.ScrubArea>
      <NumberField.Group>
        <NumberField.Decrement aria-label="Lower the price">−</NumberField.Decrement>
        <NumberField.Input />
        <NumberField.Increment aria-label="Raise the price">+</NumberField.Increment>
      </NumberField.Group>
    </NumberField.Root>
  );
}

#Styling

With the default theme, put lu-number-field on Root: the label above one bordered group, the input centred between two 36px buttons that dim at the ends of the range, and a focus ring around the whole group.

With your own CSS, style the parts through class, the input's :focus-visible, the buttons' :disabled and [data-action="increment"] / [data-action="decrement"], the scrub area's [data-scrub], and lu-number-field[data-scrubbing] while a drag is on.

@lumiose/ui/number-field.css (0.2 kB brotli) hides the native spinners once the script runs (:defined) and hides the buttons until then, keeps held buttons from selecting text, and gives a scrub area its resize cursor and touch-action: none.

#Keyboard and focus

Right to left, dragging the scrub area toward the left steps up, as a slider runs. A press on a button steps once (by largeStep with Shift, smallStep with Alt) and, with a mouse, puts focus in the input, so the arrow keys go on stepping (a touch leaves focus where it is, so no virtual keyboard opens); holding it steps again every 60 ms after 400 ms. A click from a keyboard or a screen reader on a button steps once. Every drag (the scrub area) has the arrow keys as its alternative (WCAG 2.5.7). The wheel steps the number only with allowWheelScrub, while the input has focus and the pointer is over it; otherwise the wheel scrolls the page, as over any field (Chromium's own stepping of a focused number input is turned off). Ctrl with the wheel zooms the page, and a sideways swipe never steps. Text that is no number (Firefox lets letters into a number input) goes on commit, and the last number comes back.

#Without JavaScript, and the element's script

Without format, the native number input works and submits with no script; the buttons, which need it, stay hidden and the native spinners show. With format, the text input submits its text as typed until the script moves the name to the hidden input, so a form that must work without JavaScript should leave format out.

<lu-number-field>'s script (2.6 kB brotli) adds the large step, Home and End, the buttons, the scrub area and the wheel, clamps and formats on commit, keeps the hidden input, aria-valuenow and aria-valuetext current, and follows a form reset.

#Browser support

Native number inputs and Intl.NumberFormat (with formatToParts): every supported browser. Scrubbing uses pointer capture, without pointer lock.

#Related

• Field: a label, a description and errors for a number field.
• Slider: a number picked by dragging along a range.
• Input: any other text.