Choose a version:

NumberField

The NumberField 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.

Use cases

Quantities: Collect product quantities, inventory counts, or stock levels.
Pricing: Capture pricing information, discounts, or monetary amounts.
Stepper controls: Provide stepper controls for intuitive increment/decrement interactions.
Validation: Support form submissions with proper min/max validation.

Anchor to examplesExamples

Anchor to example-capture-numeric-input-with-a-number-fieldCapture numeric input with a number field

Capture numeric input using a NumberField 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 example-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

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

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

/>;

Anchor to example-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>;

Examples

Capture numeric input with a number field
Description
Capture numeric input using a `NumberField` component. This example shows a basic number field with a label for collecting numeric values.
Default
```
<s-number-field 
  label="Item count"
  value="976"
  required
/>
```
Add stepper controls and constraints
Description
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.
Default
```
<s-number-field
  label="Quantity"
  value="5"
  min={1}
  max={100}
  controls
  onInput={(event) => console.log('Input:', event.currentTarget.value)}
  onChange={(event) => console.log('Change:', event.currentTarget.value)}
/>;
```

Configure keyboard input modes

Description

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.

Default

<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 propertiesProperties

Configure the following properties on the NumberField component.

Anchor to controls controls "auto" | "stepper" | "none": Sets the type of controls displayed for the field.

stepper: displays buttons to increase or decrease the value of the field by the stepping interval defined in the step property. Note that in POS adding stepper controls simplifies the behaviour of the Number Field itself. The field supports only integer values, is always-populated and automatically validates the value to be within the min and max bounds. Validation, label, details and placeholder are not supported when using Stepper controls.

none: no controls are displayed and users must input the value manually.

auto: the presence of the controls depends on the surface and context.
Anchor to details details string: 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.

Details are not supported when using Stepper controls
Anchor to disabled disabled boolean Default: false: Disables the field, disallowing any interaction.
Anchor to error error string: Indicate an error to the user. The field will be given a specific stylistic treatment to communicate problems that have to be resolved immediately.

Error is not supported when using Stepper controls
Anchor to id id string: A unique identifier for the element.
Anchor to inputMode inputMode "decimal" | "numeric" Default: 'decimal': Sets the virtual keyboard.

Input mode is not supported when using Stepper controls
Anchor to label label string: Content to use as the field label.

Label is not supported when using Stepper controls
Anchor to max max number Default: Infinity: The highest decimal or integer to be accepted for the field. When used with step the value will round down to the max number.

Note: a user will still be able to use the keyboard to input a number higher than the max. It is up to the developer to add appropriate validation.
Anchor to min min number Default: -Infinity: The lowest decimal or integer to be accepted for the field. When used with step the value will round up to the min number.

Note: a user will still be able to use the keyboard to input a number lower than the min. It is up to the developer to add appropriate validation.
Anchor to placeholder placeholder string: A short hint that describes the expected value of the field.

Placeholder text is not supported when using Stepper controls due to constrained space for the number field, especially on phones.
Anchor to required required boolean Default: false Required is not supported when using Stepper controls: Whether the field needs a value. This requirement adds semantic value to the field, but it will not cause an error to appear automatically. If you want to present an error when this field is empty, you can do so with the error property.
Anchor to value value string: The current value for the field. If omitted, the field will be empty.

Anchor to slotsSlots

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

Anchor to accessory accessory HTMLElement: Additional content to be displayed in the field. Commonly used to display clickable text.

Note
Accessory is not supported when using Stepper controls
Note: Accessory is not supported when using Stepper controls

Anchor to eventsEvents

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

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

CallbackEvent

bubbles
```
boolean
```
cancelable
```
boolean
```
composed
```
boolean
```
currentTarget
```
HTMLElementTagNameMap[T]
```
detail
```
any
```
eventPhase
```
number
```
target
```
HTMLElementTagNameMap[T] | null
```

interface CallbackEvent<T extends keyof HTMLElementTagNameMap> {
    currentTarget: HTMLElementTagNameMap[T];
    bubbles?: boolean;
    cancelable?: boolean;
    composed?: boolean;
    detail?: any;
    eventPhase: number;
    target: HTMLElementTagNameMap[T] | null;
}

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?

NumberField

Supported targets

Supported targets

Use cases

Anchor to examplesExamples

Anchor to example-capture-numeric-input-with-a-number-fieldCapture numeric input with a number field

Capture numeric input with a number field

Capture numeric input with a number field

Anchor to example-add-stepper-controls-and-constraintsAdd stepper controls and constraints

Add stepper controls and constraints

Anchor to example-configure-keyboard-input-modesConfigure keyboard input modes

Configure keyboard input modes

Examples

Capture numeric input with a number field

Description

Default

Add stepper controls and constraints

Description

Default

Configure keyboard input modes

Description

Default

Anchor to propertiesProperties

Anchor to slotsSlots

Anchor to eventsEvents

CallbackEvent

Anchor to best-practicesBest practices