Number Field · base-ui-svelte

API Reference

Props mirror Base UI React where applicable, adapted for Svelte 5. Native HTML attributes for the rendered element are also accepted unless noted.

NumberField.Root

Groups all parts of the number field and manages its state. Renders a <div> element.

Props

value number | null —

Name: value
Description: Controlled value.
Type: number | null | undefined

defaultValue number | null —

Name: defaultValue
Description: Uncontrolled initial value.
Type: number | null

onValueChange function —

Name: onValueChange
Description: Event handler called when the value changes.
Type: ((value: number | null, event: Event) => void) | undefined

onValueCommitted function —

Name: onValueCommitted
Description: Called when the value is committed (blur, Enter, scrub end).
Type: ((value: number | null, event: Event) => void) | undefined

min number —

Name: min
Description: The minimum value of the input element.
Type: number | undefined

max number —

Name: max
Description: The maximum value of the input element.
Type: number | undefined

step number 1

Name: step
Description: Amount to increment and decrement with the buttons and arrow keys, or to scrub with pointer movement in the scrub area. To always enable step validation on form submission, specify the min prop explicitly in conjunction with this prop. Specify step="any" to always disable step validation; interactive stepping then uses a base amount of 1, while the alt and shift keys still step by smallStep and largeStep.
Type: number
Default: 1

smallStep number 1

Name: smallStep
Description: Step used with Alt.
Type: number
Default: 1

largeStep number 10

Name: largeStep
Description: Step used with Shift.
Type: number
Default: 10

allowOutOfRange boolean false

Name: allowOutOfRange
Description: When true, skip min/max clamping.
Type: boolean
Default: false

snapOnStep boolean true

Name: snapOnStep
Description: When true, snap to step from min.
Type: boolean
Default: true

allowWheelScrub boolean false

Name: allowWheelScrub
Description: When true, focused input responds to mouse wheel.
Type: boolean
Default: false

locale Intl.LocalesArgument —

Name: locale
Description: The locale of the input element. Defaults to the user's runtime locale.
Type: Intl.LocalesArgument | undefined

format Intl.NumberFormatOptions —

Name: format
Description: Options to format the input value.
Type: Intl.NumberFormatOptions | undefined

disabled boolean false

Name: disabled
Description: Whether the control ignores user interaction.
Type: boolean
Default: false

readOnly boolean false

Name: readOnly
Description: Whether the user should be unable to change the field value.
Type: boolean
Default: false

name string —

Name: name
Description: Identifies the field when a form is submitted.
Type: string | undefined

form string —

Name: form
Description: Identifies the form that owns the hidden input. Useful when the number field is rendered outside the form.
Type: string | undefined

required boolean false

Name: required
Description: Whether the user must enter a value before submitting a form.
Type: boolean
Default: false

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet<[{ value: number | null; disabled: boolean }]>

Data attributes

Attribute	Description
`data-disabled`	Present when the number field is disabled.
`data-readonly`	Present when the number field is readonly.
`data-scrubbing`	Present while scrubbing.

NumberField.Decrement

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

Props

disabled boolean false

Name: disabled
Description: Whether the control ignores user interaction.
Type: boolean
Default: false

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet

Data attributes

Attribute	Description
`data-disabled`	Present when the number field is disabled.

NumberField.Group

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

Props

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet

Data attributes

Attribute	Description
`data-disabled`	Present when the number field is disabled.

NumberField.Increment

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

Props

disabled boolean false

Name: disabled
Description: Whether the control ignores user interaction.
Type: boolean
Default: false

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet

Data attributes

Attribute	Description
`data-disabled`	Present when the number field is disabled.

NumberField.Input

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

Props

disabled boolean false

Name: disabled
Description: Whether the control ignores user interaction.
Type: boolean
Default: false

readOnly boolean —

Name: readOnly
Description: —
Type: boolean

Data attributes

Attribute	Description
`data-disabled`	Present when the number field is disabled.
`data-readonly`	Present when the number field is readonly.

NumberField.ScrubArea

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

Props

pixelSensitivity number 2

Name: pixelSensitivity
Description: Determines how many pixels the cursor must move before the value changes. A higher value will make scrubbing less sensitive.
Type: number
Default: 2

direction 'horizontal' | 'vertical' 'horizontal'

Name: direction
Description: Cursor movement direction.
Type: 'horizontal' | 'vertical'
Default: 'horizontal'

teleportDistance number —

Name: teleportDistance
Description: Reset scrub origin when pointer travels farther than this distance from the start point.
Type: number | undefined

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet

Data attributes

Attribute	Description
`data-disabled`	Present when the number field is disabled.
`data-scrubbing`	Present while scrubbing.

A custom element to display instead of the native cursor while using the scrub area. Renders a <span> element. This component uses the [Pointer Lock API](https://developer.mozilla.org/en-US/docs/Web/API/Pointer_Lock_API), which may prompt the browser to display a related notification. It is disabled in Safari to avoid a layout shift that this notification causes there.

Props

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet

Data attributes

Attribute	Description
`data-scrubbing`	Present while scrubbing.

API Reference

NumberField.Root

NumberField.Decrement

NumberField.Group

NumberField.Increment

NumberField.Input

NumberField.ScrubArea

NumberField.ScrubAreaCursor