Choose a version:

Number field

The number field component captures numeric input with built-in number validation. Use it to collect quantities, prices, or other numeric information.

The component supports optional stepper controls, min/max constraints, and step increments for guided numeric entry.

Support

Targets (9)

Supported targets

Anchor to PropertiesProperties

Configure the following properties on the NumberField component.

Anchor to controls controls 'auto' | 'stepper' | 'none' Default: 'auto': The type of controls displayed for the field:

'auto' - An automatic setting where the presence of controls depends on the surface and context. The system determines the most appropriate control type based on the usage scenario.

'stepper' - Displays increment (+) and decrement (-) buttons for adjusting the numeric value. When stepper controls are enabled, the field behavior is constrained: it accepts only integer values, always contains a value (never empty), and automatically validates against min and max bounds. The label, details, placeholder, error, required, and inputMode properties aren't supported with stepper controls.

'none' - A control type with no visible controls where users must input the value manually using the keyboard.
Anchor to details details string: The additional text to provide context or guidance for the field. This text is displayed along with the field and its label to offer more information or instructions to the user. This will also be exposed to screen reader users.
Anchor to disabled disabled boolean Default: false: Whether the field is disabled, preventing user interaction. Use when the field is temporarily unavailable due to application state, permissions, or dependencies.
Anchor to error error string: An error message to indicate a problem to the user. The field will be given specific stylistic treatment to communicate issues that must be resolved immediately.
Anchor to id id string: A unique identifier for the element used for targeting with CSS, JavaScript, or accessibility features.
Anchor to inputMode inputMode 'decimal' | 'numeric' Default: 'decimal': The virtual keyboard layout that the field displays for numeric input. This property isn't supported when using stepper controls.

'decimal' - A keyboard layout that includes decimal point support for entering fractional numbers, prices, or measurements with decimal precision.

'numeric' - A keyboard layout optimized for integer-only entry without decimal point support, ideal for quantities, counts, or whole number values.
Anchor to label label string: The content to use as the field label that describes the numeric information being requested.
Anchor to max max number Default: Infinity: The highest decimal or integer value that the field accepts. When used with stepper controls, the value rounds down to the max number. Users can still input higher numbers by keyboard—validation should be implemented.
Anchor to min min number Default: -Infinity: The lowest decimal or integer value that the field accepts. When used with stepper controls, the value rounds up to the min number. Users can still input lower numbers by keyboard—validation should be implemented.
Anchor to placeholder placeholder string: A short hint that provides guidance about the expected value of the field.
Anchor to required required boolean Default: false Required isn't supported when using Stepper controls: Whether the field needs a value. This requirement adds semantic value to the field but doesn't cause an error to appear automatically. Use the error property to present validation errors.
Anchor to value value string: The current numeric value entered in the field. An empty string means no value is entered.

Anchor to SlotsSlots

The number field component supports slots for additional content placement within the field. Learn more about using slots.

Anchor to accessory accessory HTMLElement: The additional content to be displayed in the field. Commonly used to display clickable text or action elements. Only button and clickable components with text content only are supported in this slot. Use the slot="accessory" attribute to place elements in this area.

Anchor to EventsEvents

The number field component provides event callbacks for handling user interactions. Learn more about handling events.

Anchor to blur blur (event: <"s-number-field">) => void: Called when the element loses focus.
Anchor to change change (event: <"s-number-field">) => void: Called after editing completes, typically on blur.
Anchor to focus focus (event: <"s-number-field">) => void: Called when the element receives focus.
Anchor to input input (event: <"s-number-field">) => void: Called when the user makes any changes in the field.

CallbackEvent

Represents the event object passed to callback functions when interactive events occur. Contains metadata about the event, including the target element, event phase, and propagation behavior.

bubbles
Whether the event bubbles up through the DOM tree.
```
boolean
```
cancelable
Whether the event can be canceled.
```
boolean
```
composed
Whether the event will trigger listeners outside of a shadow root.
```
boolean
```
currentTarget
The element that the event listener is attached to.
```
HTMLElementTagNameMap[T]
```
detail
Additional data associated with the event.
```
any
```
eventPhase
The current phase of the event flow.
```
number
```
target
The element that triggered the event.
```
HTMLElementTagNameMap[T] | null
```

Anchor to ExamplesExamples

Anchor to Capture numeric input with a number fieldCapture numeric input with a number field

Capture numeric input using a number field component. This example shows a basic number field with a label for collecting numeric values.

Capture numeric input with a number field

<s-number-field

label="Item count"

value="976"

required

Anchor to Add stepper controls and constraintsAdd stepper controls and constraints

Enable stepper controls with increment and decrement buttons and set min/max constraints to limit valid input ranges. This example demonstrates using the controls property with min and max values to create bounded numeric inputs with visual stepper controls, ideal for quantity selection or limited-range numeric entry.

Add stepper controls and constraints

<s-number-field

label="Quantity"

value="5"

min={1}

max={100}

controls="stepper"

onInput={(event) => console.log('Input:', event.currentTarget.value)}

onChange={(event) => console.log('Change:', event.currentTarget.value)}

/>;

Anchor to Configure keyboard input modesConfigure keyboard input modes

Configure the keyboard layout by specifying inputMode for decimal or numeric entry. This example shows how to use the inputMode property to display appropriate mobile keyboards—numeric for integers or decimal for numbers with fractional parts—improving data entry speed and accuracy.

Configure keyboard input modes

<s-stack>

<s-number-field

label="Price"

placeholder="0.00"

inputMode="decimal"

onInput={(event) => console.log('Value:', event.currentTarget.value)}

<s-number-field

label="Stock count"

placeholder="0"

inputMode="numeric"

onInput={(event) => console.log('Value:', event.currentTarget.value)}

</s-stack>;

Anchor to Best practicesBest practices

Choose appropriate controls: Use stepper for quantities or small adjustments. Use none for prices or large values where steppers are impractical.
Select the right input mode: Use decimal for prices and measurements. Use numeric for quantities and counts.
Explain constraints in details: Use details to clarify valid ranges or formatting, like "Enter a quantity between 1 and 999."

Was this page helpful?