Number Input

A numeric input component with increment and decrement controls.

Quantity

<ui:numberInput.root defaultValue="0">
    <ui:numberInput.scrubber>
        <ui:numberInput.label>Quantity</ui:numberInput.label>
    </ui:numberInput.scrubber>
    <ui:numberInput.control>
        <ui:numberInput.decrementTrigger />
        <ui:numberInput.input />
        <ui:numberInput.incrementTrigger />
    </ui:numberInput.control>
</ui:numberInput.root>

import { mount } from 'fluid-primitives';
import { NumberInput } from 'fluid-primitives/number-input';

mount('number-input', ({ props }) => {
	const numberInput = new NumberInput(props);
	numberInput.init();
	return numberInput;
});

Features

Based on the spinbutton pattern
Supports using the scroll wheel to increment and decrement the value
Handles floating point rounding errors when incrementing, decrementing, and snapping to step
Supports pressing and holding the spin buttons to continuously increment or decrement
Supports rounding value to specific number of fraction digits
Support for scrubbing interaction
Automatically sets the locale based on Site Language

Installation

typo3 ui:add number-input

Read more about installing Components and Primitives.

Examples

With Min/Max Constraints

Pass the min prop or max prop to set an upper and lower limit for the input. By default, the input will restrict the value to stay within the specified range.

Percentage

<ui:numberInput.root min="0" max="100" step="5" defaultValue="50">
    <ui:numberInput.label>Percentage</ui:numberInput.label>
    <ui:numberInput.control>
        <ui:numberInput.decrementTrigger />
        <ui:numberInput.input />
        <ui:numberInput.incrementTrigger />
    </ui:numberInput.control>
</ui:numberInput.root>

With Format Options

You can format the input value to be rounded to specific decimal points or to be displayed as a currency by passing an object in shape of Intl.NumberFormatOptions. Note that this is a client-only API so the initial value rendered on the server will not be formatted.

Price

<ui:numberInput.root formatOptions="{style: 'currency', currency: 'USD'}" defaultValue="9.99">
    <ui:numberInput.label>Price</ui:numberInput.label>
    <ui:numberInput.control>
        <ui:numberInput.decrementTrigger />
        <ui:numberInput.input />
        <ui:numberInput.incrementTrigger />
    </ui:numberInput.control>
</ui:numberInput.root>

With Scrubber

The scrubber allows users to change the value by clicking and dragging horizontally.

Drag to adjust

<ui:numberInput.root defaultValue="50">
    <ui:numberInput.scrubber>
        <ui:numberInput.label>Drag to adjust</ui:numberInput.label>
    </ui:numberInput.scrubber>
    <ui:numberInput.control>
        <ui:numberInput.decrementTrigger />
        <ui:numberInput.input />
        <ui:numberInput.incrementTrigger />
    </ui:numberInput.control>
</ui:numberInput.root>

Mouse Wheel Support

Enable changing the value with the mouse wheel when the input is focused.

Scroll to change

<ui:numberInput.root allowMouseWheel="{true}" defaultValue="0">
    <ui:numberInput.label>Scroll to change</ui:numberInput.label>
    <ui:numberInput.control>
        <ui:numberInput.decrementTrigger />
        <ui:numberInput.input />
        <ui:numberInput.incrementTrigger />
    </ui:numberInput.control>
</ui:numberInput.root>

Localization

Default increment and decrement labels are shipped via XLF and follow the current Site Language. For per-template overrides, pass translated strings through the translations prop. Set a translation entry to {false} or an empty string to omit the corresponding aria-label.

<f:variable
    name="numberInputTranslations"
    value="{
        incrementLabel: '{f:translate(key: \'LLL:EXT:site_package/Resources/Private/Language/locallang.xlf:forms.quantity.increase\')}',
        decrementLabel: '{f:translate(key: \'LLL:EXT:site_package/Resources/Private/Language/locallang.xlf:forms.quantity.decrease\')}'
    }"
/>

<ui:numberInput.root translations="{numberInputTranslations}"> ... </ui:numberInput.root>

API Reference

The following tables cover the available props of the Fluid Primitives. For a full list of available client side props and methods, see the Zag.js Machine API.

numberInput.root

Provides shared number input state and wraps all related parts. Renders a <div> element.

Name	Description	Required	Default
`disabled`	`boolean` Whether the number input is disabled. Inherited from a surrounding field when available.	No	-
`invalid`	`boolean` Whether the number input value is invalid. Inherited from a surrounding field when available.	No	-
`required`	`boolean` Whether the number input is required. Inherited from a surrounding field when available.	No	-
`readOnly`	`boolean` Whether the number input is readonly. Inherited from a surrounding field when available.	No	-
`name`	`string` The name attribute of the number input. Useful for form submission. Inherited from a surrounding field when available.	No	-
`form`	`string` The associate form of the input element.	No	-
`defaultValue`	`string` The initial value of the input when rendered. Use when you don't need to control the value of the input. Inherited from a surrounding field when available.	No	''
`min`	`float` The minimum value of the number input.	No	-
`max`	`float` The maximum value of the number input.	No	-
`step`	`float` The amount to increment or decrement the value by.	No	-
`allowMouseWheel`	`boolean` Whether to allow mouse wheel to change the value.	No	-
`allowOverflow`	`boolean` Whether to allow the value overflow the min/max range.	No	false
`clampValueOnBlur`	`boolean` Whether to clamp the value when the input loses focus (blur).	No	true
`focusInputOnChange`	`boolean` Whether to focus input when the value changes.	No	true
`spinOnPress`	`boolean` Whether to spin the value when the increment/decrement button is pressed.	No	true
`formatOptions`	`array` The options to pass to the `Intl.NumberFormat` constructor.	No	-
`inputMode`	`string` Hints at the type of data that might be entered by the user and the keyboard shown on mobile devices.	No	'decimal'
`pattern`	`string` The pattern used to check the `<input>` element's value against.	No	'-?[0-9]*(.[0-9]+)?'
`translations`	`array` Specifies the localized strings that identify the accessibility elements and their states. Use `f:translate` for per-template localization overrides when needed.	No	-
`locale`	`string` The current locale. Inherited from the site's language.	No	-

numberInput.label

Labels the number input. Renders a <label> element.

numberInput.control

Groups the input and stepper triggers. Renders a <div> element.

numberInput.input

Provides the editable spinbutton input. Renders an <input> element.

numberInput.incrementTrigger

Increases the current value. Renders a <button> element.

numberInput.decrementTrigger

Decreases the current value. Renders a <button> element.

numberInput.scrubber

Allows changing the value by dragging. Renders a <div> element.

numberInput.valueText

Displays the formatted value as text. Renders a <span> element.

Anatomy

<primitives:numberInput.root>
    <primitives:numberInput.label />
    <primitives:numberInput.control>
        <primitives:numberInput.decrementTrigger />
        <primitives:numberInput.input />
        <primitives:numberInput.incrementTrigger />
    </primitives:numberInput.control>
    <primitives:numberInput.scrubber />
    <primitives:numberInput.valueText />
</primitives:numberInput.root>