Number Input

The <x-wirekit::number-input> component wraps a native <input type="number"> with custom increment/decrement stepper buttons. Native browser spinners are hidden in favor of styled + and - buttons that match the WireKit design system.

Basic Usage

<x-wirekit::number-input label="Quantity" name="quantity" :value="1" :min="0" :max="99" />

With Step

<x-wirekit::number-input label="Quantity in packaging units" name="quantity" :value="10" :min="0" :max="1000" :step="5" prefix="QTY" />

Decimal Input

Pass a fractional step to allow decimal entry. Common values: step="0.01" for currency / two-decimal precision, step="0.1" for measurements with one decimal, step="0.001" for engineering precision.

<x-wirekit::number-input label="Tax rate" name="tax_rate" :value="19.00" :min="0" :max="100" :step="0.01" suffix="%" />

<x-wirekit::number-input label="Height" name="height" :value="1.78" :min="0.5" :max="2.5" :step="0.1" suffix="m" />

Decimal separator: dot vs comma

The native <input type="number"> always submits form values using the dot notation (19.99, never 19,99) — this is the W3C contract and is consistent across every browser. Backend code reads request('tax_rate') as a dot-formatted string regardless of the user's locale.

For typing, modern browsers respect the user's OS / browser locale:

• An English-locale user typing into the input accepts 19.99; typing 19,99 is rejected.
• A German / French / Italian locale user typing accepts BOTH 19.99 AND 19,99. The browser internally normalizes the comma to a dot before submitting.
• Mobile keyboards on iOS / Android show the appropriate decimal separator on the numeric keypad based on the device locale.

If you need stricter control over the displayed decimal separator (for example, always-comma display in a German-only app even when a user's browser locale differs), wrap the value in a Livewire computed property and format with PHP's number_format($value, 2, ',', '.') before binding to a regular text input. The number-input stepper UI is locale-agnostic at the input level by design — it follows browser convention.

With Prefix & Suffix

<x-wirekit::number-input label="Weight" name="weight" :value="50" suffix="kg" />

<x-wirekit::number-input label="Discount" name="discount" :value="15" suffix="%" :min="0" :max="100" />

Size Variants

<x-wirekit::number-input name="n-sm" label="Small" size="sm" :value="5" :min="1" :max="99" />

<x-wirekit::number-input name="n-md" label="Medium" size="md" :value="10" :min="1" :max="999" />

<x-wirekit::number-input name="n-lg" label="Large" size="lg" :value="15" :min="1" :max="9999" />

Error State

<x-wirekit::number-input label="Age" name="age-error-demo" :value="0" error="Age must be between 1 and 120" />

With Hint

<x-wirekit::number-input label="Guests" name="guests" :value="2" :min="1" :max="10" hint="Maximum 10 guests per reservation" />

Width

Like all WireKit form components, the number input fills its container (w-full). Control the width via the parent element — number inputs are typically narrow:

<div class="max-w-[10rem]">
    <x-wirekit::number-input label="Qty" name="qty" :value="1" :min="0" :max="99" />
</div>

See Input — Width for more layout examples (grid columns, mixed widths).

Livewire Integration

Bind the field with wire:model and it shows the bound value from the first render, follows a value your component sets on the server while the field stays on the page, and sends both typing and stepper clicks to the property:

<x-wirekit::number-input label="Budget" wire:model.live="budget" min="0" />

With a model on the field, the model owns the input and the steppers follow it. The model stays on the input itself, and bound to a property declared int or float it reads the field as a number: wire:model.live goes out as wire:model.number.live, so the typed number the server sends back is not taken for a change that overwrites what the reader entered while the request was out. A property without a type, or a string one, gets the text, and the other modifiers behave as they do on a plain <input type="number">. An Alpine x-model works the same way, and without any model the value prop seeds the field.

Optimistic UI

Pass the name of the Livewire method the field should call and the value is shown before the server answers — on a stepper click at once, and for the field when you leave it:

<x-wirekit::number-input
    name="quantity"
    label="Quantity"
    :value="$quantity"
    optimistic="saveQuantity"
/>

Load wirekit-optimistic.js alongside whichever bundle you already use — below it, in your layout:

@wirekitScripts
<script src="{{ asset('vendor/wirekit/wirekit-optimistic.js') }}" defer></script>

Try it

The demo below runs the real path: the change shows immediately, the outline says it is provisional, and the server's answer either confirms it silently or takes it back.

{{-- In your app there is no host: your own Livewire component owns the method. --}}
<x-wirekit::number-input
    name="quantity"
    label="Quantity"
    :value="$quantity"
    optimistic="saveQuantity"
/>

The <livewire:demos.…> wrapper above exists only on this site — it supplies the demo methods so the page can show a real round trip. The block under it is what you write.

A refusal keeps the value — for the steppers too, and that is deliberate. Stepping is a discrete choice, so putting it back would normally cost you nothing. But this control also has a field you can type in, and a number typed while a stepper's request is still out would be overwritten when that request rolls back. Rather than let safety depend on whether you happened to be typing, neither half undoes: the value stays and says it was not saved.

The field is not marked invalid. aria-invalid means this value is wrong, and a save that failed on the network says nothing about the value.

Props

Slots

Accessibility

• Uses native <input type="number"> — inherits browser validation and AT support
• Stepper buttons are <button type="button"> with tabindex="-1" and aria-controls pointing at the field — not in the tab order, because ArrowUp / ArrowDown on the input step to the same grid points, and the native spinner these buttons replace is not a tab stop either
• Their accessible name carries the field's label when you pass one — Decrease Quantity / Increase Quantity — so a page with several number fields does not expose a row of identically named controls to a screen reader reading it in browse mode. Without a label they take the field's aria-label, and without either they read Decrease / Increase
• Native browser spinners are hidden via CSS to avoid double controls
• Arrow Up/Down keys increment/decrement by step (native behavior)
• aria-invalid="true" and aria-describedby set when error or hint are present
• min and max hold when the field is left: a typed value outside them is set to the nearest bound, an emptied field to min (or 0), and a value finer than step is rounded to it. The field then says what it did, under itself and to a screen reader, "Set to 99, the highest value allowed.", until the next keystroke. The steppers stop at the bounds
• Stepper icons are aria-hidden="true" — the button labels provide the accessible name

Keyboard Interaction

Pitfalls

• Don't omit min / max for bounded ranges. Without them, step arrows can produce invalid values that fail server-side validation — confusing for the user.
• Don't use number-input for codes / IDs. Phone numbers, OTPs, postal codes are STRINGS. Use <x-wirekit::input> with a pattern attribute to keep leading zeros and avoid scientific notation.

Design Tokens

Customization

Override defaults in config/wirekit.php:

'components' => [
    'number-input' => ['size' => 'md', 'step' => 1],
],

See Also

• Inline Edit — edit this value in place, with an explicit confirm step

Further Reading

• MDN: <input type="number">
• MDN: aria-invalid
• MDN: aria-describedby
• WAI-ARIA Spinbutton Pattern