Number Input

Enter numbers, step through values, and format them for a locale.

Use a Number Input for quantities, prices and measurements. It keeps a numeric value while showing formatted text, and steps it with the keyboard, the step buttons, or a drag on its label.

Console

import "@ui-sdk/web/number-input"
import "@ui-sdk/web/field"
import { createElement, Minus, MoveHorizontal, Plus } from "lucide"
import { log } from "./log"

function mount(root: HTMLElement) {
  root.innerHTML = `
    <ui-field>
      <ui-number-input default-value="1" min="1">
        <ui-number-input-scrub-area pixels-per-step="4">
          <ui-field-label>Quantity</ui-field-label>
          <ui-number-input-scrub-area-cursor>
            ${createElement(MoveHorizontal, { "aria-hidden": "true" }).outerHTML}
          </ui-number-input-scrub-area-cursor>
        </ui-number-input-scrub-area>
        <ui-number-input-group>
          <ui-number-input-decrement>
            <button aria-label="Decrease">
              ${createElement(Minus, { "aria-hidden": "true" }).outerHTML}
            </button>
          </ui-number-input-decrement>
          <ui-number-input-control>
            <input />
          </ui-number-input-control>
          <ui-number-input-increment>
            <button aria-label="Increase">
              ${createElement(Plus, { "aria-hidden": "true" }).outerHTML}
            </button>
          </ui-number-input-increment>
        </ui-number-input-group>
      </ui-number-input>
    </ui-field>
  `
  root
    .querySelector("ui-number-input")!
    .addEventListener("valuecommit", (event) => {
      log(root, `Quantity ${event.detail.value ?? "empty"}`)
    })
}

export { mount }

Drag the Quantity label sideways to scrub the value, or click it to focus the input. Type a number, press ArrowUp or ArrowDown, or hold a step button. The console logs the value once each change is committed.

Installation

npm install @ui-sdk/web @ui-sdk/core

Importing the component defines its elements. Import the field too if you use it. On the server the import does nothing.

import "@ui-sdk/web/number-input"
import "@ui-sdk/web/field"

Composition

Use the following composition to build a ui-number-input:

ui-number-input
├── ui-number-input-scrub-area
│   └── ui-number-input-scrub-area-cursor
└── ui-number-input-group
    ├── ui-number-input-decrement
    │   └── button
    ├── ui-number-input-control
    │   └── input
    └── ui-number-input-increment
        └── button

ui-number-input holds the numeric value. ui-number-input-group wraps the text input and the optional step buttons. ui-number-input-control wraps your own <input>, and ui-number-input-decrement and ui-number-input-increment wrap your own <button>s, which change the value and repeat while held. Put input styles and accessible names on those native elements. ui-number-input-scrub-area is optional and changes the value as you drag it.

Typing updates the value when the text is valid and within bounds. Enter or blur commits it: the text is parsed, clamped, snapped to the step, and formatted. An empty input has the value null.

Usage

Import the parts and put them together:

<script type="module">
  import "@ui-sdk/web/number-input"
</script>

<ui-number-input default-value="1" min="0">
  <ui-number-input-group>
    <ui-number-input-decrement
      ><button aria-label="Decrease">−</button></ui-number-input-decrement
    >
    <ui-number-input-control
      ><input aria-label="Quantity"
    /></ui-number-input-control>
    <ui-number-input-increment
      ><button aria-label="Increase">+</button></ui-number-input-increment
    >
  </ui-number-input-group>
</ui-number-input>

Field

Wrap the number input in Field to give it a visible label and a description.

import "@ui-sdk/web/number-input"
import "@ui-sdk/web/field"
import { createElement, Minus, Plus } from "lucide"

function mount(root: HTMLElement) {
  root.innerHTML = `
    <ui-field>
      <ui-field-label>Tickets</ui-field-label>
      <ui-number-input default-value="2" min="1">
        <ui-number-input-group>
          <ui-number-input-decrement>
            <button aria-label="Decrease">
              ${createElement(Minus, { "aria-hidden": "true" }).outerHTML}
            </button>
          </ui-number-input-decrement>
          <ui-number-input-control>
            <input />
          </ui-number-input-control>
          <ui-number-input-increment>
            <button aria-label="Increase">
              ${createElement(Plus, { "aria-hidden": "true" }).outerHTML}
            </button>
          </ui-number-input-increment>
        </ui-number-input-group>
      </ui-number-input>
      <ui-field-description>Each ticket admits one person to the workshop.</ui-field-description>
    </ui-field>
  `
}

export { mount }

Click Tickets to focus the input, then type or step its value. Screen readers read the description with the field.

Min and Max

Use min and max to set bounds. A step button disables at its bound. Typed values outside the bounds are clamped when committed.

import "@ui-sdk/web/number-input"
import "@ui-sdk/web/field"
import { createElement, Minus, Plus } from "lucide"

function mount(root: HTMLElement) {
  root.innerHTML = `
    <ui-field>
      <ui-field-label>Guests</ui-field-label>
      <ui-number-input default-value="2" min="1" max="8">
        <ui-number-input-group>
          <ui-number-input-decrement>
            <button aria-label="Decrease">
              ${createElement(Minus, { "aria-hidden": "true" }).outerHTML}
            </button>
          </ui-number-input-decrement>
          <ui-number-input-control>
            <input />
          </ui-number-input-control>
          <ui-number-input-increment>
            <button aria-label="Increase">
              ${createElement(Plus, { "aria-hidden": "true" }).outerHTML}
            </button>
          </ui-number-input-increment>
        </ui-number-input-group>
      </ui-number-input>
      <ui-field-description>Tables seat between 1 and 8 guests.</ui-field-description>
    </ui-field>
  `
}

export { mount }

Change Guests between 1 and 8. Type 20 and press Enter to clamp it to 8. At either bound, that direction's step button is disabled.

Step and Large Step

step sets the usual increment, and defaults to 1. Steps are measured from min, or from zero when no minimum is set. When they don't land on max, End and the increment button stop at the highest step below it, so stepping keeps the value on the step grid, as Slider does. Shift, Page Up and Page Down use large-step, ten steps by default, and Alt (Option) with an arrow key uses small-step, a tenth of a step. Keyboard lists every key.

import "@ui-sdk/web/number-input"
import "@ui-sdk/web/field"
import { createElement, Minus, Plus } from "lucide"

function mount(root: HTMLElement) {
  root.innerHTML = `
    <ui-field>
      <ui-field-label>Hours</ui-field-label>
      <ui-number-input default-value="1.5" min="0" max="24" step="0.25" large-step="1" small-step="0.05">
        <ui-number-input-group>
          <ui-number-input-decrement>
            <button aria-label="Decrease">
              ${createElement(Minus, { "aria-hidden": "true" }).outerHTML}
            </button>
          </ui-number-input-decrement>
          <ui-number-input-control>
            <input />
          </ui-number-input-control>
          <ui-number-input-increment>
            <button aria-label="Increase">
              ${createElement(Plus, { "aria-hidden": "true" }).outerHTML}
            </button>
          </ui-number-input-increment>
        </ui-number-input-group>
      </ui-number-input>
      <ui-field-description>Logged in quarter hours.</ui-field-description>
    </ui-field>
  `
}

export { mount }

Step Hours by 0.25. Hold Shift to move by 1, or hold Alt (Option) with an arrow key to move by 0.05. Home and End go to 0 and 24.

Format

Pass Intl.NumberFormat options through format. The input displays and parses that format while keeping a numeric value. For percentages, 0.15 is displayed as 15%, and step defaults to the smallest percent the format shows: 0.01 for whole percents, 0.0001 with two fraction digits. Set format as a property on the element; it is an object.

import "@ui-sdk/web/number-input"
import "@ui-sdk/web/field"
import { createElement, Minus, Plus } from "lucide"

const fields = [
  {
    label: "Price",
    defaultValue: 19.99,
    step: 0.01,
    format: { style: "currency", currency: "USD" },
  },
  {
    label: "Discount",
    defaultValue: 0.15,
    step: 0.01,
    format: { style: "percent" },
  },
  {
    label: "Weight",
    defaultValue: 2.5,
    step: 0.1,
    format: { style: "unit", unit: "kilogram" },
  },
] satisfies {
  label: string
  defaultValue: number
  step: number
  format: Intl.NumberFormatOptions
}[]

function mount(root: HTMLElement) {
  root.innerHTML = `
    <div data-slot="stack">
      ${fields
        .map(
          (field) => `
            <ui-field>
              <ui-field-label>${field.label}</ui-field-label>
              <ui-number-input default-value="${field.defaultValue}" step="${field.step}" min="0">
                <ui-number-input-group>
                  <ui-number-input-decrement>
                    <button aria-label="Decrease">
                      ${createElement(Minus, { "aria-hidden": "true" }).outerHTML}
                    </button>
                  </ui-number-input-decrement>
                  <ui-number-input-control>
                    <input />
                  </ui-number-input-control>
                  <ui-number-input-increment>
                    <button aria-label="Increase">
                      ${createElement(Plus, { "aria-hidden": "true" }).outerHTML}
                    </button>
                  </ui-number-input-increment>
                </ui-number-input-group>
              </ui-number-input>
            </ui-field>`
        )
        .join("")}
    </div>
  `
  root
    .querySelectorAll<HTMLElement & { format: Intl.NumberFormatOptions }>(
      "ui-number-input"
    )
    .forEach((el, index) => {
      el.format = fields[index].format
    })
}

export { mount }

Edit Price, Discount, or Weight and leave the field to format it. Try entering 5 in Price or 25% in Discount, then use the step buttons.

Locale

Set locale to choose separators, currency symbols, and grouping. Without it, the input follows the page's language or the browser's language after mounting. Server markup uses English when no locale is provided; set a locale explicitly when that first render matters.

import "@ui-sdk/web/number-input"
import "@ui-sdk/web/field"
import { createElement, Minus, Plus } from "lucide"

const fields = [
  {
    label: "Preis",
    locale: "de-DE",
    defaultValue: 1234.5,
    step: 0.01,
    format: { style: "currency", currency: "EUR" },
  },
  {
    label: "Budget",
    locale: "en-IN",
    defaultValue: 1234567,
    step: 1000,
    format: { style: "currency", currency: "INR", maximumFractionDigits: 0 },
  },
] satisfies {
  label: string
  locale: string
  defaultValue: number
  step: number
  format: Intl.NumberFormatOptions
}[]

function mount(root: HTMLElement) {
  root.innerHTML = `
    <div data-slot="stack">
      ${fields
        .map(
          (field) => `
            <ui-field>
              <ui-field-label>${field.label}</ui-field-label>
              <ui-number-input default-value="${field.defaultValue}" step="${field.step}" locale="${field.locale}" min="0">
                <ui-number-input-group>
                  <ui-number-input-decrement>
                    <button aria-label="Decrease">
                      ${createElement(Minus, { "aria-hidden": "true" }).outerHTML}
                    </button>
                  </ui-number-input-decrement>
                  <ui-number-input-control>
                    <input />
                  </ui-number-input-control>
                  <ui-number-input-increment>
                    <button aria-label="Increase">
                      ${createElement(Plus, { "aria-hidden": "true" }).outerHTML}
                    </button>
                  </ui-number-input-increment>
                </ui-number-input-group>
              </ui-number-input>
              <ui-field-description>Formatted for ${field.locale}.</ui-field-description>
            </ui-field>`
        )
        .join("")}
    </div>
  `
  root
    .querySelectorAll<HTMLElement & { format: Intl.NumberFormatOptions }>(
      "ui-number-input"
    )
    .forEach((el, index) => {
      el.format = fields[index].format
    })
}

export { mount }

Edit Preis using a comma for decimals, or step Budget to see Indian digit grouping. The displayed and accepted formats follow each field's locale.

Mouse Wheel

Set wheel to step with the mouse wheel while the input is focused. It is off by default.

import "@ui-sdk/web/number-input"
import "@ui-sdk/web/field"
import { createElement, Minus, Plus } from "lucide"

function mount(root: HTMLElement) {
  root.innerHTML = `
    <ui-field>
      <ui-field-label>Font size</ui-field-label>
      <ui-number-input default-value="16" min="8" max="72" wheel>
        <ui-number-input-group>
          <ui-number-input-decrement>
            <button aria-label="Decrease">
              ${createElement(Minus, { "aria-hidden": "true" }).outerHTML}
            </button>
          </ui-number-input-decrement>
          <ui-number-input-control>
            <input />
          </ui-number-input-control>
          <ui-number-input-increment>
            <button aria-label="Increase">
              ${createElement(Plus, { "aria-hidden": "true" }).outerHTML}
            </button>
          </ui-number-input-increment>
        </ui-number-input-group>
      </ui-number-input>
      <ui-field-description>Focus the input, then scroll over it.</ui-field-description>
    </ui-field>
  `
}

export { mount }

Focus Font size and scroll over it to change the value. Move focus away and scroll again; the value stays unchanged.

Scrub Area

ui-number-input-scrub-area changes the value while you drag it. The handle can be any element inside the number input: the label, as in the first example, or a letter or icon inside the group, as in a design tool. Right and up increase the value. orientation chooses an axis, and pixels-per-step controls how far the pointer moves per step. Shift and Alt (Option) use the large and small increments.

Console

import "@ui-sdk/web/number-input"
import { createElement, MoveHorizontal } from "lucide"
import { log } from "./log"

const fields = [
  { label: "X position", handle: "X", defaultValue: 120 },
  { label: "Y position", handle: "Y", defaultValue: 48 },
  { label: "Width", handle: "W", defaultValue: 320, min: 0 },
  { label: "Height", handle: "H", defaultValue: 240, min: 0 },
]

function mount(root: HTMLElement) {
  const title = `frame-${crypto.randomUUID()}`
  root.innerHTML = `
    <div data-slot="card" role="group" aria-labelledby="${title}">
      <h3 id="${title}">Frame</h3>
      <div data-slot="grid">
        ${fields
          .map(
            ({ label, handle, defaultValue, min }) => `
              <ui-number-input default-value="${defaultValue}"${min === undefined ? "" : ` min="${min}"`}>
                <ui-number-input-group>
                  <ui-number-input-scrub-area pixels-per-step="1">
                    <span aria-hidden="true">${handle}</span>
                    <ui-number-input-scrub-area-cursor>
                      ${createElement(MoveHorizontal, { "aria-hidden": "true" }).outerHTML}
                    </ui-number-input-scrub-area-cursor>
                  </ui-number-input-scrub-area>
                  <ui-number-input-control>
                    <input aria-label="${label}" />
                  </ui-number-input-control>
                </ui-number-input-group>
              </ui-number-input>
            `
          )
          .join("")}
      </div>
    </div>
  `
  root.querySelectorAll("ui-number-input").forEach((field, index) => {
    field.addEventListener("valuecommit", (event) => {
      log(root, `${fields[index].label} ${event.detail.value ?? "empty"}`)
    })
  })
}

export { mount }

Drag the X, Y, W or H letter sideways to change that value. Hold Shift for larger steps or Alt (Option) for smaller ones. The console logs each value when the drag ends.

Where pointer lock is available, the drag can continue past the edge of the screen. ui-number-input-scrub-area-cursor draws a replacement cursor while it is locked. The cursor is placed in the document body with an inline translation; center your icon with negative margins.

To place a scrub area outside its number input, such as on an icon in a toolbar, set the scrub area's for attribute to the number input's id. More than one scrub area can control the same field.

Disabled

Set disabled on the component or its enclosing fieldset to prevent focus, changes, and form submission.

<ui-field>
  <ui-field-label>Quantity</ui-field-label>
  <ui-number-input default-value="3" disabled>
    <ui-number-input-group>
      <ui-number-input-decrement
        ><button aria-label="Decrease">−</button></ui-number-input-decrement
      >
      <ui-number-input-control><input /></ui-number-input-control>
      <ui-number-input-increment
        ><button aria-label="Increase">+</button></ui-number-input-increment
      >
    </ui-number-input-group>
  </ui-number-input>
  <ui-field-description
    >Sold out. You can't change the quantity.</ui-field-description
  >
</ui-field>

Set disabled on one step button, on its element like <ui-number-input-increment disabled> or on the <button> inside it, to turn off only that direction. The other button still steps.

Read-Only

Set read-only to keep the value focusable and included in form data while preventing edits and steps.

<ui-field>
  <ui-field-label>Seats included</ui-field-label>
  <ui-number-input default-value="5" read-only>
    <ui-number-input-group>
      <ui-number-input-decrement
        ><button aria-label="Decrease">−</button></ui-number-input-decrement
      >
      <ui-number-input-control><input /></ui-number-input-control>
      <ui-number-input-increment
        ><button aria-label="Increase">+</button></ui-number-input-increment
      >
    </ui-number-input-group>
  </ui-number-input>
  <ui-field-description>Set by your plan.</ui-field-description>
</ui-field>

Validation

Use required to block an empty value. Field associates its error with the input and marks it invalid after an unsuccessful submit. Here, choosing Continue while Age is empty shows "Enter your age."

<form>
  <ui-field>
    <ui-field-label>Age</ui-field-label>
    <ui-number-input name="age" required min="18" max="120">
      <ui-number-input-group>
        <ui-number-input-decrement
          ><button aria-label="Decrease">−</button></ui-number-input-decrement
        >
        <ui-number-input-control><input /></ui-number-input-control>
        <ui-number-input-increment
          ><button aria-label="Increase">+</button></ui-number-input-increment
        >
      </ui-number-input-group>
    </ui-number-input>
    <ui-field-error match="valueMissing">Enter your age.</ui-field-error>
  </ui-field>
  <button type="submit">Continue</button>
</form>

Controlled

Set the element's value property, and listen for valuechange. valuechange reports valid changes while an interaction is in progress. valuecommit fires when typing is committed, a step key or button is released, or a scrub ends. Use the commit event for work that should happen after the interaction.

Console

import "@ui-sdk/web/number-input"
import "@ui-sdk/web/field"
import { createElement, Minus, Plus } from "lucide"
import { log } from "./log"

function mount(root: HTMLElement) {
  root.innerHTML = `
    <div data-slot="stack">
      <div data-slot="controls">
        <button type="button" data-value="4">Reset to 4</button>
        <button type="button" data-value="">Clear</button>
      </div>
      <ui-field>
        <ui-field-label>Servings</ui-field-label>
        <ui-number-input default-value="4" min="1" max="12">
          <ui-number-input-group>
            <ui-number-input-decrement>
              <button aria-label="Decrease">
                ${createElement(Minus, { "aria-hidden": "true" }).outerHTML}
              </button>
            </ui-number-input-decrement>
            <ui-number-input-control>
              <input />
            </ui-number-input-control>
            <ui-number-input-increment>
              <button aria-label="Increase">
                ${createElement(Plus, { "aria-hidden": "true" }).outerHTML}
              </button>
            </ui-number-input-increment>
          </ui-number-input-group>
        </ui-number-input>
      </ui-field>
    </div>
  `
  const field = root.querySelector("ui-number-input")!
  field.addEventListener("valuechange", (event) => {
    log(root, `Value ${event.detail.value ?? "empty"} (${event.detail.reason})`)
  })
  field.addEventListener("valuecommit", (event) => {
    log(
      root,
      `Committed ${event.detail.value ?? "empty"} (${event.detail.reason})`
    )
  })
  root.querySelectorAll<HTMLButtonElement>("[data-value]").forEach((button) => {
    button.addEventListener("click", () => {
      field.value = button.dataset.value ? Number(button.dataset.value) : null
    })
  })
}

export { mount }

Hold a Servings step button. The console logs each value as it changes, then one Committed line when you let go. Clear sets the value to null, and Reset to 4 restores it.

See State and Events for the shared state conventions and Reasons for the events specific to Number Input.

Controller

Use the element's api property to change or focus the input from other controls. increment() and decrement() step the value; pass { large: true } for a large step. setValue(), getValue(), and focus() cover direct updates and inspection.

Console

import "@ui-sdk/web/number-input"
import "@ui-sdk/web/field"
import { createElement, Minus, Plus } from "lucide"
import { log } from "./log"

function mount(root: HTMLElement) {
  root.innerHTML = `
    <div data-slot="stack">
      <div data-slot="controls">
        <button type="button" data-action="out">Zoom Out</button>
        <button type="button" data-action="in">Zoom In</button>
        <button type="button" data-action="reset">Actual Size</button>
        <button type="button" data-action="read">Read</button>
        <button type="button" data-action="focus">Focus</button>
      </div>
      <ui-field>
        <ui-field-label>Zoom</ui-field-label>
        <ui-number-input default-value="100" min="10" max="400" step="10">
          <ui-number-input-group>
            <ui-number-input-decrement>
              <button aria-label="Decrease">
                ${createElement(Minus, { "aria-hidden": "true" }).outerHTML}
              </button>
            </ui-number-input-decrement>
            <ui-number-input-control>
              <input />
            </ui-number-input-control>
            <ui-number-input-increment>
              <button aria-label="Increase">
                ${createElement(Plus, { "aria-hidden": "true" }).outerHTML}
              </button>
            </ui-number-input-increment>
          </ui-number-input-group>
        </ui-number-input>
      </ui-field>
    </div>
  `
  const field = root.querySelector("ui-number-input")!
  field.format = { style: "unit", unit: "percent" }
  field.addEventListener("valuechange", (event) => {
    log(root, `Zoom ${event.detail.value ?? "empty"}% (${event.detail.reason})`)
  })
  const zoom = field.api
  const actions: Record<string, () => void> = {
    out: () => zoom.decrement({ large: true }),
    in: () => zoom.increment({ large: true }),
    reset: () => zoom.setValue(100),
    read: () => log(root, `Zoom is ${zoom.getValue()}%`),
    focus: () => zoom.focus(),
  }
  root
    .querySelectorAll<HTMLButtonElement>("[data-action]")
    .forEach((button) => {
      button.addEventListener("click", () => actions[button.dataset.action!]())
    })
}

export { mount }

Press Zoom In and Zoom Out to move by 100%, then Actual Size to restore 100%. Read logs the current value, and Focus moves into the field.

Controllers covers creating and sharing a controller.

Form

The element is form-associated and submits the plain numeric value under name. Formatting does not change form data: a displayed amount of $4.50 still submits 4.5. Empty values submit an empty string.

Console

import "@ui-sdk/web/number-input"
import "@ui-sdk/web/field"
import { createElement, Minus, Plus } from "lucide"
import { log } from "./log"

let count = 0

function mount(root: HTMLElement) {
  const formId = `order-${++count}`
  root.innerHTML = `
    <div data-slot="stack">
      <form data-slot="stack" id="${formId}">
        <ui-field>
          <ui-field-label>Quantity</ui-field-label>
          <ui-number-input name="quantity" default-value="2" min="1">
            <ui-number-input-group>
              <ui-number-input-decrement>
                <button aria-label="Decrease">
                  ${createElement(Minus, { "aria-hidden": "true" }).outerHTML}
                </button>
              </ui-number-input-decrement>
              <ui-number-input-control>
                <input />
              </ui-number-input-control>
              <ui-number-input-increment>
                <button aria-label="Increase">
                  ${createElement(Plus, { "aria-hidden": "true" }).outerHTML}
                </button>
              </ui-number-input-increment>
            </ui-number-input-group>
          </ui-number-input>
        </ui-field>
        <ui-field>
          <ui-field-label>Tip</ui-field-label>
          <ui-number-input name="tip" default-value="4.5" min="0" step="0.5">
            <ui-number-input-group>
              <ui-number-input-decrement>
                <button aria-label="Decrease">
                  ${createElement(Minus, { "aria-hidden": "true" }).outerHTML}
                </button>
              </ui-number-input-decrement>
              <ui-number-input-control>
                <input />
              </ui-number-input-control>
              <ui-number-input-increment>
                <button aria-label="Increase">
                  ${createElement(Plus, { "aria-hidden": "true" }).outerHTML}
                </button>
              </ui-number-input-increment>
            </ui-number-input-group>
          </ui-number-input>
        </ui-field>
      </form>
      <ui-field>
        <ui-field-label>Gift cards</ui-field-label>
        <ui-number-input name="gift-cards" form="${formId}" default-value="0" min="0">
          <ui-number-input-group>
            <ui-number-input-decrement>
              <button aria-label="Decrease">
                ${createElement(Minus, { "aria-hidden": "true" }).outerHTML}
              </button>
            </ui-number-input-decrement>
            <ui-number-input-control>
              <input />
            </ui-number-input-control>
            <ui-number-input-increment>
              <button aria-label="Increase">
                ${createElement(Plus, { "aria-hidden": "true" }).outerHTML}
              </button>
            </ui-number-input-increment>
          </ui-number-input-group>
        </ui-number-input>
      </ui-field>
      <div data-slot="row">
        <button type="reset" form="${formId}">Reset</button>
        <button type="submit" form="${formId}" data-variant="solid">Save</button>
      </div>
    </div>
  `
  const [, tip] = root.querySelectorAll("ui-number-input")
  tip.format = { style: "currency", currency: "USD" }
  const form = root.querySelector("form")!
  form.addEventListener("submit", (event) => {
    event.preventDefault()
    const data = [...new FormData(form)].map(
      ([name, value]) => `${name}=${value}`
    )
    log(root, `Submitted ${data.join(", ")}`)
  })
}

export { mount }

Change Quantity or Tip and press Save: the console logs the plain numeric values. Gift cards belongs to the same form through its form ID. Reset restores the defaults.

Set form to associate the input with a form elsewhere in the page. A form reset restores the default value and reports the reset reason.

Custom Rendering

Elements have no render functions. The input and step buttons are your own elements, so change them directly, and read state from their data attributes or the valuechange event. Here a valuechange listener gives the decrement button a tooltip, and shows Max on the increment button once the value reaches its bound.

import "@ui-sdk/web/number-input"
import "@ui-sdk/web/field"
import { createElement, Minus, Plus } from "lucide"

function mount(root: HTMLElement) {
  root.innerHTML = `
    <ui-field>
      <ui-field-label>Temperature</ui-field-label>
      <ui-number-input default-value="-2" min="-20" max="40">
        <ui-number-input-group>
          <ui-number-input-decrement>
            <button aria-label="Colder">
              ${createElement(Minus, { "aria-hidden": "true" }).outerHTML}
            </button>
          </ui-number-input-decrement>
          <ui-number-input-control>
            <input />
          </ui-number-input-control>
          <ui-number-input-increment>
            <button aria-label="Warmer"></button>
          </ui-number-input-increment>
        </ui-number-input-group>
      </ui-number-input>
    </ui-field>
  `
  const field = root.querySelector("ui-number-input")!
  field.format = { style: "unit", unit: "celsius" }
  const colder = root.querySelector<HTMLButtonElement>('[aria-label="Colder"]')!
  const warmer = root.querySelector<HTMLButtonElement>('[aria-label="Warmer"]')!
  const plus = createElement(Plus, { "aria-hidden": "true" }).outerHTML
  const show = (value: number | null) => {
    colder.title = value === -20 ? "As cold as it goes" : "Colder"
    warmer.innerHTML = value === 40 ? "<span>Max</span>" : plus
  }
  field.addEventListener("valuechange", (event) => show(event.detail.value))
  show(field.value)
}

export { mount }

Press End in Temperature to jump to 40°C. The increment button reads Max; hover the decrement button to see its tooltip.

Each part's state is listed under State.

Styling

Style the group as the field's box, and the input and step buttons inside it. data-disabled on a step button also means it has reached its bound, and data-scrubbing marks every part while a drag changes the value. Inside Field, the native input receives validation attributes such as data-invalid. Use logical spacing so the layout follows the surrounding direction.

Each part has a data-slot, such as number-input-group, and its state attributes are listed under Data Attributes.

Data Attributes

`<ui-number-input>`

[data-slot="number-input"]

Attribute	What it means
`data-disabled`	Present when disabled, by its own prop or a `<fieldset>`.
`data-readonly`	Present when read-only.
`data-required`	Present when required.
`data-scrubbing`	Present while a drag on the scrub area changes the value.

`<ui-number-input-scrub-area>`

[data-slot="number-input-scrub-area"]

Attribute	What it means
`data-disabled`	Present when disabled, by its own prop or a `<fieldset>`.
`data-readonly`	Present when read-only.
`data-required`	Present when required.
`data-orientation`	`horizontalvertical`Which way to drag.
`data-scrubbing`	Present while a drag on the scrub area changes the value.

`<ui-number-input-scrub-area-cursor>`

[data-slot="number-input-scrub-area-cursor"]

Attribute	What it means
`data-disabled`	Present when disabled, by its own prop or a `<fieldset>`.
`data-readonly`	Present when read-only.
`data-required`	Present when required.
`data-scrubbing`	Present while a drag on the scrub area changes the value.

`<ui-number-input-group>`

[data-slot="number-input-group"]

Attribute	What it means
`data-disabled`	Present when disabled, by its own prop or a `<fieldset>`.
`data-readonly`	Present when read-only.
`data-required`	Present when required.
`data-scrubbing`	Present while a drag on the scrub area changes the value.

`<ui-number-input-decrement>`

[data-slot="number-input-decrement"]

Attribute	What it means
`data-disabled`	Present when the button can't step: it or the field is disabled, the field is read-only, or the value is at `min`.
`data-readonly`	Present when read-only.
`data-required`	Present when required.
`data-at-bound`
`data-scrubbing`	Present while a drag on the scrub area changes the value.

`<ui-number-input-control>`

[data-slot="number-input-control"]

Attribute	What it means
`data-disabled`	Present when disabled, by its own prop or a `<fieldset>`.
`data-readonly`	Present when read-only.
`data-required`	Present when required.
`data-scrubbing`	Present while a drag on the scrub area changes the value.

`<ui-number-input-increment>`

[data-slot="number-input-increment"]

Attribute	What it means
`data-disabled`	Present when the button can't step: it or the field is disabled, the field is read-only, or the value is at `max`.
`data-readonly`	Present when read-only.
`data-required`	Present when required.
`data-scrubbing`	Present while a drag on the scrub area changes the value.

API Reference

Props are attributes in kebab case, like default-value, large-step and read-only. format and controller are properties. Callbacks are DOM events.

NumberInput

value?number | null: The value, or null for an empty field. Pass it to control the field.
defaultValue?number | null: The value at first, when uncontrolled. A form reset returns to it.
valuechange event: Runs when the value changes: as a typed number becomes valid, and on every step. details.cancel() stops it.
valuecommit event: Runs once an interaction that changed the value ends: typing is committed, a key or a button is released, or a scrub ends. For saving.
min?number: The lowest value. Typed values below it are raised to it when committed.
max?number: The highest value. Typed values above it are lowered to it when committed.
step?number: How far one step moves. Committed values snap to steps from min, or from 0 without one.
largeStep?number: How far Page Up, Page Down, and Shift with an arrow key, a button, the wheel or a scrub move.
smallStep?number: How far Alt (Option on a Mac) with an arrow key, the wheel or a scrub moves, for fine changes. Values it reaches snap to it rather than to step.
format?Intl.NumberFormatOptions: How the value shows: Intl.NumberFormat options, like { style: "currency", currency: "USD" }. Typing accepts the same format in the locale, and percents are fractions: 50% is 0.5.
locale?string: The locale for formatting and reading typed numbers. Defaults to the page's lang, or the browser's language without one, once the page is interactive. Server markup uses English until then, so it never disagrees with the client.
wheel?boolean: Lets the mouse wheel step the value while the input has focus.
disabled?boolean: Disables it like a native control: it can't be focused or changed, and isn't submitted.
readOnly?boolean: Keeps it focusable and submitted, but stops changes.
required?boolean: Blocks form submission while it's empty, with the browser's own message.
name?string: The name it submits under. The number is submitted as is, like 1234.5, never formatted.
form?string: The id of a form to belong to, when it isn't inside that form.
controller?object: Steps it from anywhere. Create one with createNumberInputController().
debug?boolean: Logs every state change with its reason to the console, in development builds.

NumberInputScrubArea

orientation?"horizontal" | "vertical": Which way to drag: right and up increase.
pixelsPerStep?number: How far the pointer moves for one step, in CSS pixels.
controller?object: Connects a scrub area outside the number input, like an icon in a toolbar, to the number input with this controller. Inside it, it connects on its own. Web components use for="<number input id>" instead.

NumberInputIncrement and NumberInputDecrement

disabled?boolean: Turns off this button alone. Pressing, clicking or holding it doesn't step.

State

The same state shows as data attributes on each element.

valuenumber | null: The value, or null when empty.
disabledboolean: Whether it's disabled, by itself or by a <fieldset>.
readOnlyboolean: Whether it's read-only: it stays focusable and submitted, but typing, steps and scrubs don't change it.
requiredboolean: Whether a form won't submit while it's empty.
scrubbingboolean: Whether a scrub is moving the value.

The buttons' state, NumberInputButtonState, says whether that button can step, and whether the value is at its bound, apart from a disabled field:

valuenumber | null: The value, or null when empty.
disabledboolean: Whether it's disabled, by itself or by a <fieldset>. Whether the button can't step, because it or the field is disabled, the field is read-only, or the value is at its bound.
readOnlyboolean: Whether it's read-only: it stays focusable and submitted, but typing, steps and scrubs don't change it.
requiredboolean: Whether a form won't submit while it's empty.
scrubbingboolean: Whether a scrub is moving the value.
atBoundboolean: Whether the value is at the bound this button steps toward, like the maximum for the increment.

Reasons

event.detail.reason says why the value changed.

input-changeEvent: Typing, pasting or dropping changed a text field's value; in a combobox it can also open or close it, or Enter keeps the typed text as the value.
input-commitKeyboardEvent | FocusEvent: Enter, or leaving a number input, committed what was typed: a number input parses, clamps and snaps it to the step, and an autocomplete closes its suggestions on it.
step-keyKeyboardEvent: Arrow, Page Up, Page Down, Home or End stepped a slider or a number input.
increment-pressPointerEvent | MouseEvent: A number input's increment button was pressed, or held.
decrement-pressPointerEvent | MouseEvent: A number input's decrement button was pressed, or held.
wheelWheelEvent: The mouse wheel stepped a focused number input.
scrubPointerEvent: A drag on a number input's scrub area.
resetnone: A form reset.
restorenone: The browser restored state, like after going back, or a saved value was read back from storage.
imperativenone: A controller or api call, or a property set on a web component.

Controller

The element's api property has the same methods. The value property reads and sets the value.

Every write method takes an optional { reason, event }, fires the change event like a press, and returns false when the change is canceled.

getValue()() => number | null: The value, or null when the field is empty.
setValue(value, options?)(value: number | null, options?: NumberInputChangeOptions | undefined) => boolean: Sets the value, as a user would. It's clamped and snapped to the step.
increment(options?)(options?: (NumberInputChangeOptions & { large?: boolean | undefined; }) | undefined) => boolean: Steps the value up, by largeStep with { large: true }.
decrement(options?)(options?: (NumberInputChangeOptions & { large?: boolean | undefined; }) | undefined) => boolean: Steps the value down, by largeStep with { large: true }.
focus()() => void: Moves focus to the input.

Events

Events fire on their own element and don't bubble, with the value in event.detail.value and the reason and event beside it. Calling preventDefault() on valuechange cancels the change.

Member	On	Description
`value` property, attribute	`ui-number-input`	The value, or null when empty. An empty attribute is empty
`format` property	`ui-number-input`	`Intl.NumberFormat` options
`api` property	`ui-number-input`	The controller
`valuechange` event	`ui-number-input`	`detail: { value, reason, event, source }`, as the value changes
`valuecommit` event	`ui-number-input`	`detail: { value, reason, event, source }`, once the interaction ends

Accessibility

Follows the keyboard model of the WAI-ARIA spinbutton pattern on a native text input, so ordinary text editing works too. Give the input a FieldLabel or aria-label, and name both step buttons. Each button points to the input with aria-controls.

Keyboard

Input	Increment
ArrowUp, ArrowDown, or a step button	`step`, which defaults to 1.
Shift with an arrow or button; Page Up or Page Down	`large-step`, which defaults to ten steps.
Alt (Option) with an arrow key	`small-step`, which defaults to a tenth of a step.
Home or End	The minimum or maximum, when set.

Enter commits typed text. The step buttons stay out of the Tab order, because the focused input gives the same steps through its arrow keys.

Tested Behavior

Every line below is an automated test.

Keyboard

Starts with its default value, formatted.
ArrowUp and ArrowDown step the value.
Shift with an arrow key steps by the large step.
Home and End go to the minimum and the maximum.
Stepping stops at the bounds.
Steps keep cents exact.
The buttons aren't in the tab order.

Typing

Typing a number changes the value.
A typed value above the maximum is lowered when focus leaves.
Typed text in the format is read and formatted when focus leaves.
Typing sends change only once the text is committed.
Letters can't be typed.
Arrow keys step from what's typed.
Text that isn't a number goes back to the value when focus leaves.
The value commits when focus leaves.

Buttons

The increment and decrement buttons step the value.
A button at its bound is disabled and marked data-at-bound.
Holding a button repeats the step.
A press commits when the button is released.
A disabled button is marked disabled.
A disabled button doesn't step when clicked or held, and the other still does.
<button disabled> inside a step button element stays disabled past a bound. Web components only.
A button disabled while it's held stops repeating.

State and forms

Submits the number as is, not formatted.
A disabled field can't be focused or changed.
A read-only field can be focused, but not changed.
A required empty field blocks the form.
The mouse wheel does nothing unless turned on.
The mouse wheel steps a focused field when turned on.
A canceled change keeps the value.
A controlled field follows its value.
Reads and writes the locale's format.

Runs in React, Vue and web components.

Beyond the pattern:

Page Up and Page Down step by the large step.
A form reset returns every field to its default.
A typed value snaps to the step when focus leaves.
Enter commits and formats what's typed.
Holding an arrow key commits once, when the key comes up.
A field with cents asks for a decimal keypad.
A scrub steps by distance, whatever the speed.
A scrub that doesn't move commits nothing.

Runs in React, Vue and web components.

Screen readers hear the same thing in each tested framework, recorded by a virtual screen reader:

Announcements while moving to a number input with a keyboard.

Runs in React, Vue and web components.