Skip to contents

Number Field

A numeric input element with increment and decrement buttons, and a scrub area.

Usage guidelines

  • Form controls must have an accessible name: It can be created using a <label> element or the Field component. See the forms guide.

Anatomy

Import the component and assemble its parts:

Anatomy

API reference

Root

Groups all parts of the number field and manages its state. Renders a <div> element and a visually hidden number input for form submission.

id string | null —
Name
Description

The id of the input element.

Type
string | null
min number —
Name
Description

The minimum value.

Type
number
max number —
Name
Description

The maximum value.

Type
number
allowOutOfRange boolean false
Description

When true, direct text entry may sit outside min/max so native range validation can run. Step-based interactions still clamp.

Type
boolean
Default
false
smallStep number 0.1
Description

Step while Alt is held. Also the snap size for Alt when snapOnStep is set.

Type
number
Default
0.1
step number | 'any' 1
Name
Description

Amount to increment, decrement, or scrub. step="any" disables step validation and uses 1 for interactive stepping.

Type
number | 'any'
Default
1
largeStep number 10
Description

Step while Shift is held.

Type
number
Default
10
required boolean | null false
Description

Whether the user must enter a value before submitting a form.

Type
boolean | null
Default
false
disabled boolean | null false
Description

Whether the component should ignore user interaction.

Type
boolean | null
Default
false
readonly boolean | null false
Description

Whether the user should be unable to change the field value.

Type
boolean | null
Default
false
name string | null —
Name
Description

Identifies the field when a form is submitted.

Type
string | null
form string | null —
Name
Description

Identifies the form that owns the hidden input.

Type
string | null
value number | null —
Name
Description

Raw numeric value. Use bind:value to share it with the parent.

Type
number | null
Binding
bind:value
defaultValue number | null null
Description

The value an empty value starts from, as on an HTML input.

Type
number | null
Default
null
allowWheelScrub boolean false
Description

Whether wheel scrubbing changes the value while the input is focused.

Type
boolean
Default
false
snapOnStep boolean false
Description

Whether stepping snaps to a multiple of the active step.

Type
boolean
Default
false
format Intl.NumberFormatOptions —
Name
Description

Options to format the input value.

Type
Intl.NumberFormatOptions
onValueChange function —
Description

Called when the numeric value changes. eventDetails.cancel() vetoes the change. eventDetails.reason says what triggered it.

Type
(value: number | null, eventDetails: NumberFieldChangeEventDetails) => void
onValueCommitted function —
Description

Called when the value is committed: blur after typing, pointer release after scrubbing or holding a step button, or immediately for keyboard and wheel.

Type
(value: number | null, eventDetails: NumberFieldCommitEventDetails) => void
locale Intl.LocalesArgument —
Name
Description

Locale used to format and parse. Defaults to the runtime locale.

Type
Intl.LocalesArgument
render Snippet<[props: HTMLAttributes<HTMLDivElement>, state: NumberFieldRootState, children: Snippet | undefined]> —
Name
Description

Replace the default <div>. Spread props onto the host and render children.

Type
Snippet<[props: HTMLAttributes<HTMLDivElement>, state: NumberFieldRootState, children: Snippet | undefined]>
value number | null
Name
value
Description

The raw numeric value of the field.

Type
number | null
inputValue string
Name
inputValue
Description

The formatted string presented in the input.

Type
string
required boolean
Name
required
Description

Whether the user must enter a value before submitting a form.

Type
boolean
disabled boolean
Name
disabled
Description

Whether the component should ignore user interaction.

Type
boolean
readOnly boolean
Name
readOnly
Description

Whether the user should be unable to change the field value.

Type
boolean
scrubbing boolean
Name
scrubbing
Description

Whether the user is currently scrubbing the field.

Type
boolean
touched boolean
Name
touched
Description

Whether the field has been touched.

Type
boolean
dirty boolean
Name
dirty
Description

Whether the field value has changed from its initial value.

Type
boolean
valid boolean | null
Name
valid
Description

Whether the field is valid. null means validity is not known yet.

Type
boolean | null
filled boolean
Name
filled
Description

Whether the field has a value.

Type
boolean
focused boolean
Name
focused
Description

Whether the field is focused.

Type
boolean
data-disabled
Present when the number field is disabled.
data-readonly
Present when the number field is readonly.
data-required
Present when the number field is required.
data-valid
Present when the number field is in a valid state (when wrapped in Field.Root).
data-invalid
Present when the number field is in an invalid state (when wrapped in Field.Root).
data-dirty
Present when the number field's value has changed (when wrapped in Field.Root).
data-touched
Present when the number field has been touched (when wrapped in Field.Root).
data-filled
Present when the number field is filled (when wrapped in Field.Root).
data-focused
Present when the number field is focused (when wrapped in Field.Root).
data-scrubbing
Present while scrubbing.

ScrubArea

An interactive area where the user can click and drag to change the field value. Renders a <span> element.

direction 'horizontal' | 'vertical' 'horizontal'
Description

Cursor movement direction.

Type
'horizontal' | 'vertical'
Default
'horizontal'
pixelSensitivity number 2
Description

How many pixels the cursor must move before the value changes.

Type
number
Default
2
teleportDistance number —
Description

Distance from the center of the scrub area before the cursor loops. Omit it to use the visual viewport.

Type
number
render Snippet<[props: HTMLAttributes<HTMLSpanElement>, state: NumberFieldScrubAreaState, children: Snippet | undefined]> —
Name
Description

Replace the default <span>. Spread props onto the host and render children.

Type
Snippet<[props: HTMLAttributes<HTMLSpanElement>, state: NumberFieldScrubAreaState, children: Snippet | undefined]>
value number | null
Name
value
Description

The raw numeric value of the field.

Type
number | null
inputValue string
Name
inputValue
Description

The formatted string presented in the input.

Type
string
required boolean
Name
required
Description

Whether the user must enter a value before submitting a form.

Type
boolean
disabled boolean
Name
disabled
Description

Whether the component should ignore user interaction.

Type
boolean
readOnly boolean
Name
readOnly
Description

Whether the user should be unable to change the field value.

Type
boolean
scrubbing boolean
Name
scrubbing
Description

Whether the user is currently scrubbing the field.

Type
boolean
touched boolean
Name
touched
Description

Whether the field has been touched.

Type
boolean
dirty boolean
Name
dirty
Description

Whether the field value has changed from its initial value.

Type
boolean
valid boolean | null
Name
valid
Description

Whether the field is valid. null means validity is not known yet.

Type
boolean | null
filled boolean
Name
filled
Description

Whether the field has a value.

Type
boolean
focused boolean
Name
focused
Description

Whether the field is focused.

Type
boolean
data-disabled
Present when the number field is disabled.
data-readonly
Present when the number field is readonly.
data-required
Present when the number field is required.
data-valid
Present when the number field is in a valid state (when wrapped in Field.Root).
data-invalid
Present when the number field is in an invalid state (when wrapped in Field.Root).
data-dirty
Present when the number field's value has changed (when wrapped in Field.Root).
data-touched
Present when the number field has been touched (when wrapped in Field.Root).
data-filled
Present when the number field is filled (when wrapped in Field.Root).
data-focused
Present when the number field is focused (when wrapped in Field.Root).
data-scrubbing
Present while scrubbing.

ScrubAreaCursor

A custom element to display instead of the native cursor while using the scrub area. Renders a <span> element, moved to document.body while scrubbing.

render Snippet<[props: HTMLAttributes<HTMLSpanElement>, state: NumberFieldScrubAreaCursorState, children: Snippet | undefined]> —
Name
Description

Replace the default <span>. Spread props onto the host and render children.

Type
Snippet<[props: HTMLAttributes<HTMLSpanElement>, state: NumberFieldScrubAreaCursorState, children: Snippet | undefined]>
value number | null
Name
value
Description

The raw numeric value of the field.

Type
number | null
inputValue string
Name
inputValue
Description

The formatted string presented in the input.

Type
string
required boolean
Name
required
Description

Whether the user must enter a value before submitting a form.

Type
boolean
disabled boolean
Name
disabled
Description

Whether the component should ignore user interaction.

Type
boolean
readOnly boolean
Name
readOnly
Description

Whether the user should be unable to change the field value.

Type
boolean
scrubbing boolean
Name
scrubbing
Description

Whether the user is currently scrubbing the field.

Type
boolean
touched boolean
Name
touched
Description

Whether the field has been touched.

Type
boolean
dirty boolean
Name
dirty
Description

Whether the field value has changed from its initial value.

Type
boolean
valid boolean | null
Name
valid
Description

Whether the field is valid. null means validity is not known yet.

Type
boolean | null
filled boolean
Name
filled
Description

Whether the field has a value.

Type
boolean
focused boolean
Name
focused
Description

Whether the field is focused.

Type
boolean
data-disabled
Present when the number field is disabled.
data-readonly
Present when the number field is readonly.
data-required
Present when the number field is required.
data-valid
Present when the number field is in a valid state (when wrapped in Field.Root).
data-invalid
Present when the number field is in an invalid state (when wrapped in Field.Root).
data-dirty
Present when the number field's value has changed (when wrapped in Field.Root).
data-touched
Present when the number field has been touched (when wrapped in Field.Root).
data-filled
Present when the number field is filled (when wrapped in Field.Root).
data-focused
Present when the number field is focused (when wrapped in Field.Root).
data-scrubbing
Present while scrubbing.

Group

Groups the input with the increment and decrement buttons. Renders a <div> element.

render Snippet<[props: HTMLAttributes<HTMLDivElement>, state: NumberFieldGroupState, children: Snippet | undefined]> —
Name
Description

Replace the default <div>. Spread props onto the host and render children.

Type
Snippet<[props: HTMLAttributes<HTMLDivElement>, state: NumberFieldGroupState, children: Snippet | undefined]>
value number | null
Name
value
Description

The raw numeric value of the field.

Type
number | null
inputValue string
Name
inputValue
Description

The formatted string presented in the input.

Type
string
required boolean
Name
required
Description

Whether the user must enter a value before submitting a form.

Type
boolean
disabled boolean
Name
disabled
Description

Whether the component should ignore user interaction.

Type
boolean
readOnly boolean
Name
readOnly
Description

Whether the user should be unable to change the field value.

Type
boolean
scrubbing boolean
Name
scrubbing
Description

Whether the user is currently scrubbing the field.

Type
boolean
touched boolean
Name
touched
Description

Whether the field has been touched.

Type
boolean
dirty boolean
Name
dirty
Description

Whether the field value has changed from its initial value.

Type
boolean
valid boolean | null
Name
valid
Description

Whether the field is valid. null means validity is not known yet.

Type
boolean | null
filled boolean
Name
filled
Description

Whether the field has a value.

Type
boolean
focused boolean
Name
focused
Description

Whether the field is focused.

Type
boolean
data-disabled
Present when the number field is disabled.
data-readonly
Present when the number field is readonly.
data-required
Present when the number field is required.
data-valid
Present when the number field is in a valid state (when wrapped in Field.Root).
data-invalid
Present when the number field is in an invalid state (when wrapped in Field.Root).
data-dirty
Present when the number field's value has changed (when wrapped in Field.Root).
data-touched
Present when the number field has been touched (when wrapped in Field.Root).
data-filled
Present when the number field is filled (when wrapped in Field.Root).
data-focused
Present when the number field is focused (when wrapped in Field.Root).
data-scrubbing
Present while scrubbing.

Decrement

A stepper button that decreases the field value when clicked. Renders a <button> element.

nativeButton boolean true
Description

Whether the rendered element is a native <button>.

Type
boolean
Default
true
render Snippet<[props: HTMLAttributes<HTMLButtonElement>, state: NumberFieldStepperState, children: Snippet | undefined]> —
Name
Description

Replace the default <button>. Spread props onto the host and render children.

Type
Snippet<[props: HTMLAttributes<HTMLButtonElement>, state: NumberFieldStepperState, children: Snippet | undefined]>
value number | null
Name
value
Description

The raw numeric value of the field.

Type
number | null
inputValue string
Name
inputValue
Description

The formatted string presented in the input.

Type
string
required boolean
Name
required
Description

Whether the user must enter a value before submitting a form.

Type
boolean
disabled boolean
Name
disabled
Description

Whether the component should ignore user interaction.

Type
boolean
readOnly boolean
Name
readOnly
Description

Whether the user should be unable to change the field value.

Type
boolean
scrubbing boolean
Name
scrubbing
Description

Whether the user is currently scrubbing the field.

Type
boolean
touched boolean
Name
touched
Description

Whether the field has been touched.

Type
boolean
dirty boolean
Name
dirty
Description

Whether the field value has changed from its initial value.

Type
boolean
valid boolean | null
Name
valid
Description

Whether the field is valid. null means validity is not known yet.

Type
boolean | null
filled boolean
Name
filled
Description

Whether the field has a value.

Type
boolean
focused boolean
Name
focused
Description

Whether the field is focused.

Type
boolean
data-disabled
Present when the number field is disabled.
data-readonly
Present when the number field is readonly.
data-required
Present when the number field is required.
data-valid
Present when the number field is in a valid state (when wrapped in Field.Root).
data-invalid
Present when the number field is in an invalid state (when wrapped in Field.Root).
data-dirty
Present when the number field's value has changed (when wrapped in Field.Root).
data-touched
Present when the number field has been touched (when wrapped in Field.Root).
data-filled
Present when the number field is filled (when wrapped in Field.Root).
data-focused
Present when the number field is focused (when wrapped in Field.Root).
data-scrubbing
Present while scrubbing.

Input

The native input control in the number field. Renders an <input> element.

aria-roledescription string | null 'Number field'
Description

Role description for assistive tech. This is not the accessible name.

Type
string | null
Default
'Number field'
render Snippet<[props: HTMLAttributes<HTMLElement>, state: NumberFieldInputState, children: Snippet | undefined]> —
Name
Description

Replace the default <input>. Spread props onto the host element.

Type
Snippet<[props: HTMLAttributes<HTMLElement>, state: NumberFieldInputState, children: Snippet | undefined]>
value number | null
Name
value
Description

The raw numeric value of the field.

Type
number | null
inputValue string
Name
inputValue
Description

The formatted string presented in the input.

Type
string
required boolean
Name
required
Description

Whether the user must enter a value before submitting a form.

Type
boolean
disabled boolean
Name
disabled
Description

Whether the component should ignore user interaction.

Type
boolean
readOnly boolean
Name
readOnly
Description

Whether the user should be unable to change the field value.

Type
boolean
scrubbing boolean
Name
scrubbing
Description

Whether the user is currently scrubbing the field.

Type
boolean
touched boolean
Name
touched
Description

Whether the field has been touched.

Type
boolean
dirty boolean
Name
dirty
Description

Whether the field value has changed from its initial value.

Type
boolean
valid boolean | null
Name
valid
Description

Whether the field is valid. null means validity is not known yet.

Type
boolean | null
filled boolean
Name
filled
Description

Whether the field has a value.

Type
boolean
focused boolean
Name
focused
Description

Whether the field is focused.

Type
boolean
data-disabled
Present when the number field is disabled.
data-readonly
Present when the number field is readonly.
data-required
Present when the number field is required.
data-valid
Present when the number field is in a valid state (when wrapped in Field.Root).
data-invalid
Present when the number field is in an invalid state (when wrapped in Field.Root).
data-dirty
Present when the number field's value has changed (when wrapped in Field.Root).
data-touched
Present when the number field has been touched (when wrapped in Field.Root).
data-filled
Present when the number field is filled (when wrapped in Field.Root).
data-focused
Present when the number field is focused (when wrapped in Field.Root).
data-scrubbing
Present while scrubbing.

Increment

A stepper button that increases the field value when clicked. Renders a <button> element.

nativeButton boolean true
Description

Whether the rendered element is a native <button>.

Type
boolean
Default
true
render Snippet<[props: HTMLAttributes<HTMLButtonElement>, state: NumberFieldStepperState, children: Snippet | undefined]> —
Name
Description

Replace the default <button>. Spread props onto the host and render children.

Type
Snippet<[props: HTMLAttributes<HTMLButtonElement>, state: NumberFieldStepperState, children: Snippet | undefined]>
value number | null
Name
value
Description

The raw numeric value of the field.

Type
number | null
inputValue string
Name
inputValue
Description

The formatted string presented in the input.

Type
string
required boolean
Name
required
Description

Whether the user must enter a value before submitting a form.

Type
boolean
disabled boolean
Name
disabled
Description

Whether the component should ignore user interaction.

Type
boolean
readOnly boolean
Name
readOnly
Description

Whether the user should be unable to change the field value.

Type
boolean
scrubbing boolean
Name
scrubbing
Description

Whether the user is currently scrubbing the field.

Type
boolean
touched boolean
Name
touched
Description

Whether the field has been touched.

Type
boolean
dirty boolean
Name
dirty
Description

Whether the field value has changed from its initial value.

Type
boolean
valid boolean | null
Name
valid
Description

Whether the field is valid. null means validity is not known yet.

Type
boolean | null
filled boolean
Name
filled
Description

Whether the field has a value.

Type
boolean
focused boolean
Name
focused
Description

Whether the field is focused.

Type
boolean
data-disabled
Present when the number field is disabled.
data-readonly
Present when the number field is readonly.
data-required
Present when the number field is required.
data-valid
Present when the number field is in a valid state (when wrapped in Field.Root).
data-invalid
Present when the number field is in an invalid state (when wrapped in Field.Root).
data-dirty
Present when the number field's value has changed (when wrapped in Field.Root).
data-touched
Present when the number field has been touched (when wrapped in Field.Root).
data-filled
Present when the number field is filled (when wrapped in Field.Root).
data-focused
Present when the number field is focused (when wrapped in Field.Root).
data-scrubbing
Present while scrubbing.