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 theFieldcomponent. See the forms guide.
Anatomy
Import the component and assemble its parts:
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
- Name
- Description
When true, direct text entry may sit outside
min/maxso native range validation can run. Step-based interactions still clamp.- Type
boolean- Default
false
smallStep number 0.1
- Name
- Description
Step while Alt is held. Also the snap size for Alt when
snapOnStepis set.- Type
number- Default
0.1
step number | 'any' 1
- Name
- Description
Amount to increment, decrement, or scrub.
step="any"disables step validation and uses1for interactive stepping.- Type
number | 'any'- Default
1
largeStep number 10
- Name
- Description
Step while Shift is held.
- Type
number- Default
10
required boolean | null false
- Name
- Description
Whether the user must enter a value before submitting a form.
- Type
boolean | null- Default
false
disabled boolean | null false
- Name
- Description
Whether the component should ignore user interaction.
- Type
boolean | null- Default
false
readonly boolean | null false
- Name
- 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:valueto share it with the parent.- Type
number | null- Binding
bind:value
defaultValue number | null null
- Name
- Description
The value an empty
valuestarts from, as on an HTML input.- Type
number | null- Default
null
allowWheelScrub boolean false
- Name
- Description
Whether wheel scrubbing changes the value while the input is focused.
- Type
boolean- Default
false
snapOnStep boolean false
- Name
- 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 —
- Name
- Description
Called when the numeric value changes.
eventDetails.cancel()vetoes the change.eventDetails.reasonsays what triggered it.- Type
(value: number | null, eventDetails: NumberFieldChangeEventDetails) => void
onValueCommitted function —
- Name
- 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>. Spreadpropsonto the host and renderchildren.- 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.
nullmeans 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
data-readonly
data-required
data-valid
data-invalid
data-dirty
data-touched
data-filled
data-focused
data-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'
- Name
- Description
Cursor movement direction.
- Type
'horizontal' | 'vertical'- Default
'horizontal'
pixelSensitivity number 2
- Name
- Description
How many pixels the cursor must move before the value changes.
- Type
number- Default
2
teleportDistance number —
- Name
- 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>. Spreadpropsonto the host and renderchildren.- 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.
nullmeans 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
data-readonly
data-required
data-valid
data-invalid
data-dirty
data-touched
data-filled
data-focused
data-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>. Spreadpropsonto the host and renderchildren.- 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.
nullmeans 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
data-readonly
data-required
data-valid
data-invalid
data-dirty
data-touched
data-filled
data-focused
data-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>. Spreadpropsonto the host and renderchildren.- 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.
nullmeans 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
data-readonly
data-required
data-valid
data-invalid
data-dirty
data-touched
data-filled
data-focused
data-scrubbing
Decrement
A stepper button that decreases the field value when clicked. Renders a <button> element.
nativeButton boolean true
- Name
- 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>. Spreadpropsonto the host and renderchildren.- 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.
nullmeans 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
data-readonly
data-required
data-valid
data-invalid
data-dirty
data-touched
data-filled
data-focused
data-scrubbing
Input
The native input control in the number field. Renders an <input> element.
aria-roledescription string | null 'Number field'
- Name
- 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>. Spreadpropsonto 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.
nullmeans 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
data-readonly
data-required
data-valid
data-invalid
data-dirty
data-touched
data-filled
data-focused
data-scrubbing
Increment
A stepper button that increases the field value when clicked. Renders a <button> element.
nativeButton boolean true
- Name
- 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>. Spreadpropsonto the host and renderchildren.- 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.
nullmeans 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