Number

Collect a number from customers, optionally limited to a range and a step, such as "1 to 10" or "multiples of 5".

Overview

Number is an input option type that provides a numeric input field. It only accepts numbers, and you can limit it with a Lowest value, a Highest value and a Step, which are checked when the customer adds to cart.

Use Number for:

• Quantity specifications
• Measurement values
• Age or year inputs
• Numeric preferences
• Dimensional specifications

Key characteristics:

• Numeric-only input field
• Can be marked as required
• Supports placeholder text
• Optional Lowest value, Highest value and Step, enforced at Add to cart
• Mobile numeric keyboard
• Fully stylable via per-type templates, including optional − and + buttons (see Number Styling)

Configuration

Basic Settings

Setting	Description
Label	Option name displayed to customers (e.g., "Quantity")
Option is required for this option set	If enabled, customers must enter a number before adding to cart
Hide Label from storefront	If enabled, only the input field is shown (label is hidden)

Advanced Settings

Setting	Description
Internal Label	Admin-only identifier (replaces label in options list)
Help Text	Additional guidance shown to customers (based on display mode)
Placeholder	Gray text shown inside empty input field (e.g., "Enter quantity")
Lowest value	The smallest number a customer can enter. Empty means no minimum — see Range and Step
Highest value	The largest number a customer can enter. Empty means no limit
Step	The increment between allowed numbers, e.g. 1 for whole numbers or 0.5 for halves. Empty allows any number
CSS class	Your own class name(s) on this option's container — see CSS Class & CSS ID
CSS ID	Your own HTML ID on this option's container — see CSS Class & CSS ID

Range and Step

Lowest value, Highest value and Step are all empty by default, and a Number option with none of them set accepts any number, as it always has. Fill in any of them to limit what customers can enter. All three accept 0, negative numbers and decimals.

Setting	Options (default)	What it controls
Lowest value	number (empty — No minimum)	In-app help: The smallest number a customer can enter.
Highest value	number (empty — No limit)	In-app help: The largest number a customer can enter.
Step	number above 0 (empty — Any number)	In-app help: The increment between allowed numbers, e.g. 1 for whole numbers or 0.5 for halves. Leave empty to allow any number.

Step limits what customers can enter

Step isn't only how far the arrows move. It decides which numbers are accepted at all. Allowed numbers are counted from the Lowest value, or from 0 when there's no Lowest value:

Lowest value	Step	Accepted	Rejected
1	2	1, 3, 5, 7…	2, 4, 6
empty	5	…−5, 0, 5, 10…	3, 12
0	0.5	0, 0.5, 1, 1.5…	0.25
1	empty	any number from 1 up, decimals included	0.5

Decimal steps work as you'd expect: with Step 0.1, 0.3 is accepted.

Saving

The option set can't be saved while the range breaks a rule. The message shows under the field to fix:

Message	Cause
Step must be greater than 0.	Step is 0 or negative
Highest value must be greater than the lowest value.	Highest value is equal to or below Lowest value
This value isn't reachable with the current configuration. Adjust the lowest value, highest value, or step, so the highest lands on a step.	With a Step set, Highest value isn't on a step. For example Lowest 1, Highest 6, Step 2: the steps are 1, 3, 5, 7, so 6 can't be entered
Value must be between -2,147,483,647 and 2,147,483,647.	A value is too large to store

Once a range is set, the option's summary in the option set editor shows it as chips, for example 1–7, ≥ 0, ≤ 10 and Step 1.

On the Storefront

The range is checked when the customer presses Add to cart. An entry that doesn't fit blocks Add to cart and shows a message under the field:

Message	When
Enter a number from 1 to 6	Outside the range, with both Lowest and Highest value set
Enter a number of 1 or more	Below the Lowest value, with no Highest value
Enter a number of 6 or less	Above the Highest value, with no Lowest value
Enter a number in steps of 2, starting at 1	Not on a step, with a Lowest value
Enter a multiple of 5	Not on a step, with no Lowest value

• The range is checked before the step, so an entry that's out of range and off a step shows the range message
• An empty field isn't checked against the range: only Option is required decides whether it can be left empty
• The Up and Down arrow keys in the field move by the Step (by 1 when there's none) and stop at the Lowest and Highest value
• With a Number template that shows − and + buttons, the buttons follow the same Lowest value, Highest value and Step

These messages are always shown in English. They aren't in Language Settings yet.

How to Add Number

1. Navigate to Option Sets and open your option set
2. Click Add Option
3. Select Number from the Option Type modal
4. Enter a Label (e.g., "Number of Items")
5. Check Option is required if numeric input is mandatory
6. (Optional) Click Advanced Settings to add Placeholder or Help Text, or to set a Lowest value, Highest value and Step
7. (Optional) Click Style Settings to assign a Number template
8. Click Save in the contextual save bar

Use Cases

Quantity Input

Label: Quantity Needed Required: Yes Lowest value: 10 Step: 1 Help Text: Minimum order: 10 units

Result: Required whole-number field. Anything below 10 is refused with "Enter a number of 10 or more"

Age Specification

Label: Age Required: No Lowest value / Highest value: 0 / 120 Step: 1 Placeholder: Enter age

Result: Optional age field that accepts whole numbers from 0 to 120, and can be left empty

Measurement Value

Label: Length (inches) Required: Yes Lowest value / Highest value: 1 / 96 Step: 0.5 Help Text: Enter the desired length in inches

Result: Required length in half-inch increments. 12.5 is accepted, 12.25 isn't

Year Selection

Label: Year Required: No Lowest value / Highest value: 1900 / 2026 Step: 1 Placeholder: YYYY Internal Label: Customer Specified Year

Result: Optional year field limited to real years

Packs of Five

Label: Custom Quantity Required: Yes Lowest value: 5 Step: 5 Help Text: Sold in packs of 5

Result: Accepts 5, 10, 15 and so on. 12 is refused with "Enter a number in steps of 5, starting at 5"

Styling

With no template assigned, Number input fields inherit styling from your theme and customization settings:

• Colors: Input background, text, border, and placeholder colors from Colors
• Border: Input border thickness from Borders & Shapes
• Radius: Input corner radius from Borders & Shapes
• Spacing: Option spacing between fields from Borders & Shapes

For more control, assign a Number template. It styles the field, the label and the help text, and can add − and + buttons beside the number. See Number Styling.

Best Practices

Set the range instead of describing it:

• Use Lowest value and Highest value for limits rather than relying on Help Text alone
• Use Step 1 when only whole numbers make sense
• Still mention the range in the Placeholder or Help Text ("1–10") so customers know it before they press Add to cart

Use clear placeholders:

• Show expected range or format
• Include units if applicable (inches, kg, etc.)
• Keep it simple and clear

Make sure the highest value is reachable:

• With a Step, the Highest value has to land on a step counted from the Lowest value
• Lowest 0, Highest 100, Step 5 works. Lowest 1, Highest 100, Step 5 doesn't, because the steps are 1, 6, 11… 96, 101

Set appropriate requirements:

• Required for essential quantities or measurements
• Optional for preferences or additional info — an empty optional field is never checked against the range
• Test edge cases: the lowest and highest values, a decimal, a number off the step

Mobile optimization:

• Triggers numeric keyboard on mobile
• Test on actual mobile devices
• Consider a Number template with − and + buttons for small counts that are easier to tap than type

Label with units:

• Include units in label: "Length (inches)" vs "Length"
• Be specific about measurement system
• Match customer expectations

Related

• Number Styling - Field look, − and + buttons, labels and help text
• Slider - Pick a number from a fixed range by dragging a handle
• Formula - Up to three measurements turned into one result, such as an area
• Short Text - Single-line text input
• Date - Date picker input
• Internal Label - Admin-only identification
• Help Text - Additional context display
• Placeholder - Input field placeholder text
• Required Fields - Making options required