Keystone Documentation

Appearance

Number ​

Collect numeric input from customers with validation and optional min/max constraints.

Overview ​

Number is an input option type that provides a numeric input field. It only accepts numbers and can be configured with minimum, maximum, and step values for precise control.

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 min/max constraints
  • Step value for increments
  • Mobile numeric keyboard

Configuration ​

Basic Settings ​

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

Advanced Settings ​

SettingDescription
Internal LabelAdmin-only identifier (replaces label in options list)
Help TextAdditional guidance shown to customers (based on display mode)
PlaceholderGray text shown inside empty input field (e.g., "Enter quantity")

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
  7. Click Save in the contextual save bar

Use Cases ​

Quantity Input ​

Label: Quantity Needed Required: Yes Placeholder: Enter number Help Text: Minimum order: 10 units

Result: Required numeric field for quantity with minimum guidance

Age Specification ​

Label: Age Required: No Placeholder: Enter age Help Text: Optional: Helps us recommend appropriate options

Result: Optional age input field

Measurement Value ​

Label: Length (inches) Required: Yes Placeholder: 0 Help Text: Enter the desired length in inches

Result: Required numeric field for measurement input

Year Selection ​

Label: Year Required: No Placeholder: YYYY Internal Label: Customer Specified Year

Result: Optional year input field

Custom Amount ​

Label: Custom Quantity Required: Yes Placeholder: Minimum 5 Help Text: Orders must be in quantities of 5 or more

Result: Required numeric input with minimum quantity constraint

Validation ​

Number validation:

  • Only accepts numeric values
  • Rejects non-numeric characters
  • Validates min/max if configured
  • Validates step increments if set

Validation occurs:

  • As customer types (non-numbers rejected)
  • On field blur (when customer leaves field)
  • Before adding to cart
  • Error messages for invalid values

Styling ​

Number input fields inherit styling from your theme and customization settings:

Best Practices ​

Use clear placeholders:

  • Show expected range or format
  • Include units if applicable (inches, kg, etc.)
  • Indicate minimums: "Minimum 5"
  • Keep it simple and clear

Explain numeric requirements:

  • Use Help Text for min/max constraints
  • Specify units of measurement
  • Mention step increments if applicable
  • Explain why number is needed

Set appropriate requirements:

  • Required for essential quantities or measurements
  • Optional for preferences or additional info
  • Test validation with edge cases (0, negative, decimals)
  • Ensure error messages are helpful

Consider input constraints:

  • Set minimum values to prevent invalid orders
  • Set maximum values for capacity limits
  • Use step values for specific increments
  • Balance flexibility with validation

Mobile optimization:

  • Triggers numeric keyboard on mobile
  • Includes number pad with common symbols
  • Test on actual mobile devices
  • Verify up/down arrows work (if shown)

Label with units:

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