J3W1 / DESIGN SYSTEM

Number field

The text-field box around a native number input with right-aligned tabular digits, an optional unit affix and two square stepper buttons that replace the host spinner.

stable · LIGHT DOM · 1.1.0

Visible native controls retain FormData, labels, constraints, disabled fieldsets and reset. No duplicate form-value mechanism is installed.

Standalone example ↗Copy file manifest Canonical JSON Vue gallery ↗Prepare an agent kit →

Live variants

default

Workspaces

Between 1 and 20.

✕ Between 1 and 20.

<j3w1-number-field id="example-number-field-default"><div class="number-field">
  <label class="number-field-label" for="example-number-field-default-nf-workspaces">Workspaces</label>
  <div class="number-field-root">
    <input class="number-field-input" id="example-number-field-default-nf-workspaces" type="number" value="10" min="1" max="20" step="1" aria-describedby="example-number-field-default-nf-workspaces-help example-number-field-default-nf-workspaces-message" name="example-number-field-default-nf-workspaces">
    <span class="number-field-stepper">
      <button class="number-field-action" type="button" aria-label="Increase workspaces">+</button>
      <button class="number-field-action" type="button" aria-label="Decrease workspaces">−</button>
    </span>
  </div>
  <p class="number-field-help" id="example-number-field-default-nf-workspaces-help">Between 1 and 20.</p>
  <p class="number-field-message" id="example-number-field-default-nf-workspaces-message">✕ Between 1 and 20.</p>
</div></j3w1-number-field>

with-unit

Inner gap (px)

Between 0 and 64 pixels; Up and Down step by one.

✕ Between 0 and 64.

<j3w1-number-field id="example-number-field-with-unit"><div class="number-field">
  <label class="number-field-label" for="example-number-field-with-unit-nf-gap">Inner gap (px)</label>
  <div class="number-field-root">
    <input class="number-field-input" id="example-number-field-with-unit-nf-gap" type="number" value="14" min="0" max="64" step="1" aria-describedby="example-number-field-with-unit-nf-gap-help example-number-field-with-unit-nf-gap-message" name="example-number-field-with-unit-nf-gap">
    <span class="number-field-unit" aria-hidden="true">px</span>
    <span class="number-field-stepper">
      <button class="number-field-action" type="button" aria-label="Increase inner gap">+</button>
      <button class="number-field-action" type="button" aria-label="Decrease inner gap">−</button>
    </span>
  </div>
  <p class="number-field-help" id="example-number-field-with-unit-nf-gap-help">Between 0 and 64 pixels; Up and Down step by one.</p>
  <p class="number-field-message" id="example-number-field-with-unit-nf-gap-message">✕ Between 0 and 64.</p>
</div></j3w1-number-field>

Install and register

Use the exact version. If npm publication is pending, install the release tarball from the installation guide.

npm install --save-exact @j3w1/ui@1.1.0

import '@j3w1/ui/tokens.css';
import '@j3w1/ui/styles/number-field.css';
import '@j3w1/ui/register/number-field';

Insert the maintained markup above after loading these imports. Its native children provide accessible names and form behavior; the empty custom tag alone does not create a control.

Vue SFC, React, Astro and plain HTML integration →

Copy the complete implementation

npx --package=@j3w1/ui@1.1.0 j3w1-ui copy number-field --out ./vendor/j3w1/number-field

The CLI verifies every file before writing and refuses overwrites. Serve the output over HTTP and open index.html. Keep its modules, CSS, tokens and licence notices together.

Public API

attributes

Name	Type / signature	Meaning
`disabled`	`CustomEvent`	Disable the native controls owned by this instance.
`loading`	`CustomEvent`	Mark the primary control busy and prevent duplicate activation.
`value`	`CustomEvent`	Forwards value to the primary native control.
`required`	`CustomEvent`	Forwards required to the primary native control.
`readonly`	`CustomEvent`	Forwards readonly to the primary native control.
`checked`	`CustomEvent`	Forwards checked to the primary native control.

properties

Name	Type / signature	Meaning
`disabled`	`boolean`	Delegates disabled state to native children.
`name`	`string`	Native control name; application form keys remain explicit.
`value`	`string`	Primary native value; assignment does not fabricate user events.
`checked`	`boolean`	Native checkbox state.
`required`	`boolean`	Native required constraint.
`readOnly`	`boolean`	Native readonly property.
`form`	`HTMLFormElement \| null`	Owning native form. Read only.

methods

Name	Type / signature	Meaning
`refresh`	`(): void`	Reconnect behavior after replacing native child structure.
`focus`	`(options?: FocusOptions): void`	Focus the first usable native control.
`checkValidity`	`(): boolean`	Check owned native constraints.
`reportValidity`	`(): boolean`	Report the first invalid owned control.
`clear`	`(): void`	Clear an editable primary input and emit native input/change.
`stepBy`	`(amount: number): void`	Step a number input by the supplied number of native steps.

events

Name	Type / signature	Meaning
`j3w1-change`	`CustomEvent`	Native change from an owned control, alongside the original native event.

Dependencies and verification

Registered components: none. Style dependencies: none.

Package presence establishes an available implementation. Actual passes depend on the tested artifact and environment. Read specification execution evidence; read packed-consumer evidence; inspect the complete state matrix.

Full implementation manifest, API and token dependency closure

Canonical specification

Purpose

Entering a bounded number: a gap in pixels, a timeout in milliseconds, a count. The theme replaces the host spinner, which is tiny and inconsistent, with two square buttons that are real tab stops. Free-form numeric text such as a version or an identifier is a text field with inputmode.

Anatomy

Label above; the box; the input with digits aligned to the end; the optional unit; the stepper with + over −, each button half the control height and at least 24px wide; help stating the range; the validation message.

States

State	Visual	Non-colour channel
default	1px `color.border.control` on `color.surface.input`; digits `color.text.default`; unit `color.text.muted`; stepper glyphs `color.action.tertiary.text`	—
hover	background → `color.interaction.hover.bg`; a hovered stepper button → `color.action.tertiary.hover-bg`	cursor: text on the input, pointer on the buttons
focus-visible	border → `color.border.active`; ring 1px dashed `color.interaction.focus.ring` at −2px on the box, or on the focused stepper button	the ring
invalid	border 2px `color.status.danger.border`; message with the ✕ glyph	border width 1 → 2px; glyph; `aria-invalid`
invalid+focus-visible	the 2px danger border and the ring in `color.interaction.focus.ring-container` at −4px	double boundary
disabled	text, unit and glyphs `color.text.disabled`; border `color.border.disabled`; background `color.interaction.disabled.bg`; buttons disabled	`disabled`; cursor: not-allowed
read-only	no box: 1px dotted `color.border.divider` bottom edge on `color.surface.canvas`; the stepper is hidden	`readonly`; dotted edge; no buttons

Precedence: disabled > invalid > hover; focus-visible is always drawn.

Keyboard

Native arrow stepping inside the input; the stepper buttons are ordinary buttons after it in the tab order and call stepUp() / stepDown(). Typing a value outside the range is allowed and reported as invalid on blur or submit, never clamped silently.

Accessibility

A programmatic label is required. The unit is aria-hidden and repeated in the label or help (“Inner gap (px)”), so it is never lost. Stepper buttons are named “Increase ” and “Decrease ”. Help states min, max and step before the user types. aria-invalid only after interaction or submit. Contrast: digits 8.65:1, unit 5.81:1, glyphs 8.65:1, control border 4.45:1, invalid border 4.69:1.

Portability

The text field’s box plus two buttons; the host spinner is hidden with the engine’s pseudo-elements and appearance: textfield. Hosts whose spin buttons cannot be replaced style them square in the same colours and record it.

Non-examples

The host’s default spinner. Round or overlapping stepper buttons. A value clamped silently on blur. Left-aligned digits. A unit typed into the value. A number field for phone numbers, postcodes or identifiers. Invalid shown by colour alone. Disabling by opacity.