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 min/max constraints and step increments for guided numeric entry. For monetary values with currency formatting, use money field.

Anchor to Use casesUse cases

Quantity input: Collect product quantities, stock levels, or inventory thresholds.
Pricing: Capture price values, discounts, or monetary amounts with validation.
Thresholds: Set numeric thresholds for alerts, reorder points, or limits.
Measurements: Input dimensions, weights, or other numeric product attributes.

Anchor to PropertiesProperties

Configure the following properties on the number field component.

Anchor to value value string: The current value for the field. If omitted, the field will be empty.
Anchor to inputMode inputMode "decimal" | "numeric" Default: 'decimal': The type of virtual keyboard to display on mobile devices.

decimal: Shows a numeric keyboard with a decimal point, suitable for prices or measurements.

numeric: Shows a numeric keyboard without a decimal point, suitable for whole numbers like quantities.

Learn more about the inputmode attribute.
Anchor to step step number Default: 1: The amount the value can increase or decrease by. This can be an integer or decimal. If a max or min is specified with step when increasing/decreasing the value via the buttons, the final value will always round to the max or min rather than the closest valid amount.
Anchor to max max number Default: Infinity: The highest decimal or integer value accepted for the field. When used with step, the value rounds down to the maximum number.

Users can still type values higher than the maximum using the keyboard. Implement validation to enforce this constraint.
Anchor to min min number Default: -Infinity: The lowest decimal or integer value accepted for the field. When used with step, the value rounds up to the minimum number.

Users can still type values lower than the minimum using the keyboard. Implement validation to enforce this constraint.
Anchor to prefix prefix string Default: '': A non-editable text value displayed immediately before the editable portion of the field. This is useful for displaying an implied part of the value, such as https:// or +353.

This text can't be edited by the user and is not included in the field's value. The prefix might not appear until the user interacts with the field. For example, an inline label might occupy the prefix position until the user focuses the field.
Anchor to suffix suffix string Default: '': A non-editable text value displayed immediately after the editable portion of the field. This is useful for displaying an implied part of the value, such as @shopify.com or %.

This text can't be edited by the user and is not included in the field's value. The suffix might not appear until the user interacts with the field. For example, an inline label might occupy the suffix position until the user focuses the field.
Anchor to autocomplete autocomplete "on" | "off" | | `section-${string} one-time-code` | `section-${string} cc-number` | `section-${string} cc-csc` | "shipping one-time-code" | "shipping cc-number" | "shipping cc-csc" | "billing one-time-code" | ... 7 more ... | `section-${string} billing cc-csc` Default: 'on' for everything else: A hint as to the intended content of the field.

When set to on (the default), this property indicates that the field should support autofill, but you do not have any more semantic information on the intended contents.

When set to off, you are indicating that this field contains sensitive information, or contents that are never saved, like one-time codes.

Alternatively, you can provide value which describes the specific data you would like to be entered into this field during autofill.
Anchor to defaultValue defaultValue string: The initial value of the field when it first loads. Unlike placeholder, this is a real value that the user can edit and that gets submitted with the form. Once the user starts typing, their input replaces it. Changing this property after the field has loaded has no effect. To update the field value at any time, use value instead.
Anchor to details details any: Supplementary text displayed below the checkbox to provide additional context, instructions, or help. Use this to explain what checking the box means or provide guidance to users. This text is announced to screen readers.
Anchor to error error any: An error message displayed below the checkbox to indicate validation problems. When set, the checkbox is styled with error indicators and the message is announced to screen readers.
Anchor to label label any: The text displayed as the field label, which identifies the purpose of the field to users. This label is associated with the field for accessibility and helps users understand what information to provide.
Anchor to labelAccessibilityVisibility labelAccessibilityVisibility "visible" | "exclusive" Default: 'visible': Controls whether the label is visible to all users or only to screen readers.

visible: The label is shown to everyone (default).

exclusive: The label is visually hidden but still announced by screen readers.

Use exclusive when the surrounding context makes the label redundant visually, but screen reader users still need it for clarity.
Anchor to placeholder placeholder string: The placeholder text displayed in the field when it's empty, providing a hint about the expected input format or value.
Anchor to readOnly readOnly boolean Default: false: Whether the field is read-only and can't be edited. Read-only fields remain focusable and their content is announced by screen readers.
Anchor to required required boolean Default: false: Whether the field requires a value before form submission. Displays a visual indicator and adds semantic meaning, but doesn't automatically validate or show errors. Use the error property to display validation messages.
Anchor to disabled disabled boolean Default: false: Whether the field is disabled, preventing any user interaction.
Anchor to id id string: A unique identifier for the element. Use this to reference the element in JavaScript, link labels to form controls, or target specific elements for styling or scripting.
Anchor to name name string: The name attribute for the field, used to identify the field's value when the form is submitted. Must be unique within the nearest containing form.

NumberAutocompleteField

Represents autocomplete values that are valid for number input fields. This is a subset of `AnyAutocompleteField` containing only fields suitable for numeric inputs. Available values: - `one-time-code` - One-time codes for authentication (OTP, 2FA codes) - `cc-number` - Credit card number - `cc-csc` - Credit card security code (CVV/CVC)

'one-time-code' | 'cc-number' | 'cc-csc'

Anchor to EventsEvents

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

Anchor to blur blur <'input'>: A callback fired when the number field loses focus.

Learn more about the blur event.
Anchor to change change <'input'>: A callback fired when the number field value changes.

Learn more about the change event.
Anchor to focus focus <'input'>: A callback fired when the number field receives focus.

Learn more about the focus event.
Anchor to input input <'input'>: A callback fired when the user inputs data into the number field.

Learn more about the input event.

CallbackEventListener

A function that handles events from UI components. This type represents an event listener callback that receives a `CallbackEvent` with a strongly-typed `currentTarget`. Use this for component event handlers like `click`, `focus`, `blur`, and other DOM events.

(EventListener & {
      (event: CallbackEvent<T>): void;
    }) | null

CallbackEvent

An event object with a strongly-typed `currentTarget` property that references the specific HTML element that triggered the event. This type extends the standard DOM `Event` interface and ensures type safety when accessing the element that fired the event.

Event & {
  currentTarget: HTMLElementTagNameMap[T];
}

Anchor to ExamplesExamples

Anchor to Add a basic number fieldAdd a basic number field

Collect a numeric value from merchants with step controls and a defined range. This example shows a number field with a label, placeholder, step increment, and min/max bounds.

Preview

html

<s-number-field

label="Quantity"

details="Number of items in stock"

placeholder="0"

step="5"

min="0"

max="100"

></s-number-field>

Anchor to Add a prefix and suffix for currency inputAdd a prefix and suffix for currency input

Add a prefix and suffix to provide context for the expected value, such as a currency symbol or unit. This example shows a price field with a dollar sign prefix, currency suffix, and decimal input mode.

Preview

html

<s-number-field

label="Product price"

value="29.99"

prefix="$"

suffix="CAD"

inputMode="decimal"

step="0.01"

min="0"

></s-number-field>

Anchor to Show a validation errorShow a validation error

Display an error message when a value is outside the accepted range or a required field is empty. This example shows a required number field with an error indicating the minimum allowed value.

Preview

html

<s-number-field

label="Order quantity"

value="0"

min="1"

max="999"

step="1"

required

error="Quantity must be at least 1"

></s-number-field>

Anchor to Disable or make a number field read-onlyDisable or make a number field read-only

Prevent editing by making a number field read-only or fully disabled. This example shows a read-only price field and a disabled tax rate field, both with pre-filled values.

Preview

html

<s-stack gap="base">

<s-number-field

label="Base price"

value="49.99"

prefix="$"

readOnly

></s-number-field>

<s-number-field

label="Tax rate"

value="13"

suffix="%"

disabled

></s-number-field>

</s-stack>

Anchor to Best practicesBest practices

Use for numeric-only input: Choose the component when you need strictly numeric values like quantities, measurements, or percentages. For values that might contain letters or symbols (like product codes or phone numbers), use text field instead.
Provide context with units: Display units of measurement using prefix or suffix to clarify what the number represents. Without context, merchants might not know if they're entering dollars, kilograms, or percentages.
Set realistic constraints: Define minimum and maximum values that reflect actual business rules. This guides merchants toward valid inputs and prevents unrealistic values before form submission.
Validate and provide clear feedback: Always validate numeric input and show specific error messages that explain what went wrong and how to fix it. Generic error messages don't help merchants understand what value to enter.

Anchor to LimitationsLimitations

Setting inputMode suggests a keyboard layout on mobile but doesn't prevent merchants from entering non-numeric characters. Always validate input values in your change event handler.

Was this page helpful?