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	-

Rendered data attributes

Attribute	Description
`data-scope`	number-input
`data-part`	root
`data-disabled`	Present when disabled
`data-focus`	Present when focused
`data-invalid`	Present when invalid
`data-scrubbing`

numberInput.label

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

Rendered data attributes

Attribute	Description
`data-scope`	number-input
`data-part`	label
`data-disabled`	Present when disabled
`data-focus`	Present when focused
`data-invalid`	Present when invalid
`data-required`	Present when required
`data-scrubbing`

numberInput.control

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

Rendered data attributes

Attribute	Description
`data-scope`	number-input
`data-part`	control
`data-focus`	Present when focused
`data-disabled`	Present when disabled
`data-invalid`	Present when invalid
`data-scrubbing`

numberInput.input

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

Rendered data attributes

Attribute	Description
`data-scope`	number-input
`data-part`	input
`data-invalid`	Present when invalid
`data-disabled`	Present when disabled
`data-scrubbing`

numberInput.incrementTrigger

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

Rendered data attributes

Attribute	Description
`data-scope`	number-input
`data-part`	increment-trigger
`data-disabled`	Present when disabled
`data-scrubbing`

numberInput.decrementTrigger

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

Rendered data attributes

Attribute	Description
`data-scope`	number-input
`data-part`	decrement-trigger
`data-disabled`	Present when disabled
`data-scrubbing`

numberInput.scrubber

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

Rendered data attributes

Attribute	Description
`data-scope`	number-input
`data-part`	scrubber
`data-disabled`	Present when disabled
`data-scrubbing`

numberInput.valueText

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

Rendered data attributes

Attribute	Description
`data-scope`	number-input
`data-part`	value-text
`data-disabled`	Present when disabled
`data-invalid`	Present when invalid
`data-focus`	Present when focused
`data-scrubbing`

Machine JavaScript API

Name	Type	Description
`focused`	`boolean`	Whether the input is focused.
`invalid`	`boolean`	Whether the input is invalid.
`empty`	`boolean`	Whether the input value is empty.
`value`	`string`	The formatted value of the input.
`valueAsNumber`	`number`	The value of the input as a number.
`setValue`	`(value: number) => void`	Function to set the value of the input.
`clearValue`	`VoidFunction`	Function to clear the value of the input.
`increment`	`VoidFunction`	Function to increment the value of the input by the step.
`decrement`	`VoidFunction`	Function to decrement the value of the input by the step.
`setToMax`	`VoidFunction`	Function to set the value of the input to the max.
`setToMin`	`VoidFunction`	Function to set the value of the input to the min.
`focus`	`VoidFunction`	Function to focus the input.

Accessibility

Key	Description
`ArrowUp`	Increments the value of the number input by a predefined step.
`ArrowDown`	Decrements the value of the number input by a predefined step.
`Shift + ArrowUp`	Increments the value of the number input by the `largeStep` amount.
`Shift + ArrowDown`	Decrements the value of the number input by the `largeStep` amount.
`Alt + ArrowUp`	Increments the value of the number input by the `smallStep` amount.
`Alt + ArrowDown`	Decrements the value of the number input by the `smallStep` amount.
`Home`	Sets the value of the number input to its minimum allowed value.
`End`	Sets the value of the number input to its maximum allowed value.
`Enter`	Submits the value entered in the number input.

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>

Number Input

Features

Installation

Examples

With Min/Max Constraints

With Format Options

With Scrubber

Mouse Wheel Support

Localization

API Reference

numberInput.root

Rendered data attributes

numberInput.label

Rendered data attributes

numberInput.control

Rendered data attributes

numberInput.input

Rendered data attributes

numberInput.incrementTrigger

Rendered data attributes

numberInput.decrementTrigger

Rendered data attributes

numberInput.scrubber

Rendered data attributes

numberInput.valueText

Rendered data attributes

Machine JavaScript API

Accessibility

Anatomy

On this page