--- title: NumberField description: Captures numeric input from merchants. Provides built-in number validation and appropriate keyboard layout for numeric entry. api_version: 2025-10 api_name: pos-ui-extensions source_url: html: https://shopify.dev/docs/api/pos-ui-extensions/latest/polaris-web-componentsforms/numberfield md: https://shopify.dev/docs/api/pos-ui-extensions/latest/polaris-web-componentsforms/numberfield.md --- # Number​Field Captures numeric input from merchants. Provides built-in number validation and appropriate keyboard layout for numeric entry. ## Properties * 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. * 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 * disabled boolean Default: false Disables the field, disallowing any interaction. * 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 * id string A unique identifier for the element. * inputMode 'decimal' | 'numeric' Default: 'decimal' Sets the virtual keyboard. Input mode is not supported when using Stepper controls * label string Content to use as the field label. Label is not supported when using Stepper controls * 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. * 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. * 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. * 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. * value string The current value for the field. If omitted, the field will be empty. ## Slots Learn more about using [slots](https://shopify.dev/docs/api/pos-ui-extensions/using-polaris-components#slots) * 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 ## Events Learn more about registering [events](https://shopify.dev/docs/api/pos-ui-extensions/using-polaris-components#events) * blur (event: CallbackEvent<"s-number-field">) => void Callback when the element loses focus. * change (event: CallbackEvent<"s-number-field">) => void Callback after editing completes (typically on blur). * focus (event: CallbackEvent<"s-number-field">) => void Callback when the element receives focus. * input (event: CallbackEvent<"s-number-field">) => void Callback when the user makes any changes in the field. ### CallbackEvent * bubbles ```ts boolean ``` * cancelable ```ts boolean ``` * composed ```ts boolean ``` * currentTarget ```ts HTMLElementTagNameMap[T] ``` * detail ```ts any ``` * eventPhase ```ts number ``` * target ```ts HTMLElementTagNameMap[T] | null ``` ```ts interface CallbackEvent { currentTarget: HTMLElementTagNameMap[T]; bubbles?: boolean; cancelable?: boolean; composed?: boolean; detail?: any; eventPhase: number; target: HTMLElementTagNameMap[T] | null; } ``` ### Examples * #### Code ##### Default ```html ``` ## Preview ![](https://shopify.dev/images/templated-apis-screenshots/pos-ui-extensions/2025-10/number-field-default.png) ## Examples NumberField usage patterns ### Examples * #### Controls and constraints ##### Description Use controls for increment/decrement buttons and set min/max constraints ##### Default ```jsx console.log('Input:', event.currentTarget.value)} onChange={(event) => console.log('Change:', event.currentTarget.value)} />; ``` * #### Input modes ##### Description Specify inputMode for decimal or numeric keyboard layouts ##### Default ```jsx console.log('Value:', event.currentTarget.value)} /> console.log('Value:', event.currentTarget.value)} /> ; ```