Numbers, one file.

API reference

The complete NumberInput API — constructor modes, every option, instance methods, pure static helpers, declarative attributes, theming and accessibility.

Constructor & usage

new NumberInput(target, options?)   // → instance
NumberInput.create(target, options?) // same as new

target is a selector string or an element, in one of two modes:

• Enhance mode — an existing <input> is enhanced in place: its type is coerced to text with inputmode="decimal", and everything is restored by destroy(). A name on the original input migrates to the hidden raw-value carrier for the widget's lifetime (and back on destroy()), so the server never sees the formatted text.
• Container mode — any other element: the input is built inside it. Use the value option for the initial value and set ariaLabel (no external <label> can point at the generated input).

<input id="price" value="1234.5">
new NumberInput('#price', { prefix: '$', precision: 2, min: 0 })

<div id="amount"></div>
new NumberInput('#amount', { ariaLabel: 'Amount', value: 1234.5, name: 'amount' })

Constructing on an element that already has an instance? Use NumberInput.get(el) to retrieve the existing one. SSR-safe: without a DOM the constructor is a no-op and the pure helpers still work in Node.

Options

Every key of NumberInput.defaults, with its default value. Options are merged over the defaults; undefined values are ignored.

Methods

Statics & helpers

FormatOptions — the opts for parse/format

Both helpers normalize the same formatting-relevant subset of the constructor options. All keys are optional:

NumberInput.parse('$1,234.50')                        // → 1234.5
NumberInput.format(1234.5,  { precision: 2 })         // → '1,234.50'
NumberInput.format(1234.56, { decimal: ',', thousands: '.', precision: 2 })
                                                      // → '1.234,56'

Callbacks

NumberInput reports through the two option callbacks (it dispatches no custom DOM events):

• onChange(value | null) — the committed value: parse → clamp to min/max → round to precision. Fires on blur, Enter, arrow-key steps and the stepper buttons.
• onInput(value | null) — the live value on every keystroke, before any clamping.

On Enter the commit happens first and the hidden form field is already synced before a surrounding form submits. Paste is sanitized ('$1,234.50' becomes 1234.5), and out-of-range text shows a danger border while typing until the commit clamps it.

Declarative init

Add data-vnum to an <input> or container — instances are built on DOMContentLoaded (or call NumberInput.autoInit(root) after inserting markup).

<input data-vnum data-prefix="$" data-precision="2" data-min="0">

Theming

Auto light/dark with the family's resolution order: <html data-theme> / data-bs-theme / .dark class → prefers-color-scheme, re-resolved live. Pin per instance with theme: 'dark'. All colors are CSS custom properties on .vnum:

.vnum {
  --vnum-accent: #b45309;  /* focus ring, active stepper */
  --vnum-bg: …; --vnum-text: …; --vnum-muted: …; --vnum-faint: …;
  --vnum-danger: …;        /* out-of-range warning border */
  --vnum-radius: 10px; --vnum-font: …; --vnum-shadow: …;
}

With the VC core loaded, VC.config({ accent: '#b45309' }) themes this and every other family component in one call. The widget renders as class="vnum vc1"; structural rules ship salted so host design systems can't override them, while the unsalted --vnum-* variable definitions keep page overrides working. Change the token with NumberInput.salt = 'acme' (or false) before the first instance.

Headless: NumberInput.defaults.styles = false (or per instance) injects no CSS at all — you keep formatting, caret math, steppers and ARIA, and style this markup contract yourself (NumberInput.css is the reference stylesheet as a string):

.vnum[data-theme=light|dark]          ← .vnum-invalid while out of range,
  .vnum-affix.vnum-prefix               .vnum-disabled when disabled
  .vnum-input                         ← role=spinbutton, inputmode=decimal
  .vnum-affix.vnum-suffix
  .vnum-steps                         ← aria-hidden
    .vnum-btn.vnum-up
    .vnum-btn.vnum-down
  input[type=hidden]                  ← raw value, when `name` given

Accessibility

The input is role="spinbutton" with aria-valuemin/max/now and aria-valuetext (the fully formatted text, e.g. $1,234.50). The stepper buttons are aria-hidden and out of the tab order — they duplicate the arrow keys — but stay fully clickable with hold-to-repeat. Keystrokes that can't lead to a valid number are rejected; - is allowed only when allowNegative and only leading. Reduced motion is respected.

Headless mode

With styles: false NumberInput injects no CSS at all — the full behavior (formatting, caret math, steppers), the ARIA contract and the stable .vnum-* class hooks all remain; you bring the stylesheet. The demos below each run in their own <iframe>: the styled examples above have already injected the component stylesheet into this page, so only a separate, clean document can show what headless truly looks like.

new NumberInput('#demo', {
  ariaLabel: 'Amount', value: 1234.5,
  prefix: '$', precision: 2, min: 0,
  styles: false   // ← zero CSS injected
})

<style type="text/tailwindcss">
  .vnum        { @apply inline-flex items-stretch overflow-hidden rounded-2xl
                 bg-white ring-2 ring-emerald-200 shadow-lg shadow-emerald-100
                 focus-within:ring-emerald-500; }
  .vnum-affix  { @apply flex items-center bg-emerald-50 px-3 text-sm
                 font-bold text-emerald-600; }
  .vnum-input  { @apply w-32 border-0 bg-transparent px-3 py-2.5 text-right
                 text-base font-semibold text-slate-800 outline-none; }
  .vnum-steps  { @apply flex flex-col; }
  .vnum-btn    { @apply flex flex-1 cursor-pointer items-center justify-center
                 border-0 bg-emerald-500 px-3 text-white hover:bg-emerald-600
                 active:bg-emerald-700; }
  .vnum-down   { @apply border-t border-emerald-400; }
  .vnum.vnum-invalid  { @apply ring-rose-400; }
  .vnum.vnum-disabled { @apply opacity-40; }
</style>