numberInput

Create numeric input fields with validation, constraints, and unit support

Overview

The numberInput method creates a numeric input field with support for minimum/maximum values, step intervals, and prefix/suffix units. It ensures users can only enter valid numeric values.

Method Signature

numberInput(
  name: string,
  params: FormFieldSharedParamsType & NumberInputParamsType
): string

Parameters

name · string · required

The unique identifier for this input field. Used to reference the numeric value in form submissions.

Required Parameters

question · string · required

The main question or label displayed to the user.

Input-Specific Parameters

placeholder · string

Placeholder text displayed when the input is empty.

placeholder: "Enter amount"

min · number

Sets the minimum allowed value.

min: 0  // No negative values

max · number

Sets the maximum allowed value.

max: 100

step · number

Sets the stepping interval for the input. Used by increment/decrement buttons.

step: 0.01  // Allows decimals to 2 places
step: 5     // Increments by 5
step: 10    // Increments by 10

unit · string

Text displayed before the input as a unit prefix (e.g., currency symbols).

unit: "$"   // Shows: $ [input]
unit: "€"   // Shows: € [input]
unit: "£"   // Shows: £ [input]

unitEnd · string

Text displayed after the input as a unit suffix.

unitEnd: "kg"   // Shows: [input] kg
unitEnd: "%"    // Shows: [input] %
unitEnd: "mph"  // Shows: [input] mph

value · number

Sets the default numeric value.

value: 100

Shared Parameters

All standard form field parameters are supported. See textInput for the complete list including required, description, fieldSize, disabled, and more.

Examples

Basic Number

const composer = new Composer({ title: "Survey Form" });

composer.numberInput("age", {
  question: "What is your age?",
  required: true,
  min: 18,
  max: 120,
  placeholder: "Enter your age"
});

Use Cases by Unit Type

Currency

Use unit for currency symbols:

// US Dollars
composer.numberInput("price", {
  question: "Enter price",
  unit: "$",
  min: 0,
  step: 0.01
});

// Euros
composer.numberInput("amount", {
  question: "Amount",
  unit: "€",
  min: 0,
  step: 0.01
});

// British Pounds
composer.numberInput("cost", {
  question: "Total cost",
  unit: "£",
  min: 0,
  step: 0.01
});

// Yen (no decimals)
composer.numberInput("yen", {
  question: "Price in yen",
  unit: "¥",
  min: 0,
  step: 1
});

Measurements

Use unitEnd for measurement units:

// Weight
composer.numberInput("weight", {
  question: "Weight",
  unitEnd: "kg",
  min: 0,
  step: 0.1
});

// Distance
composer.numberInput("distance", {
  question: "Distance",
  unitEnd: "km",
  min: 0,
  step: 0.1
});

// Height
composer.numberInput("height", {
  question: "Height",
  unitEnd: "cm",
  min: 0,
  max: 300
});

// Volume
composer.numberInput("volume", {
  question: "Volume",
  unitEnd: "L",
  min: 0,
  step: 0.1
});

Percentages

Use unitEnd: "%" for percentages:

// Discount
composer.numberInput("discount", {
  question: "Discount",
  unitEnd: "%",
  min: 0,
  max: 100,
  step: 5
});

// Completion rate
composer.numberInput("progress", {
  question: "Progress",
  unitEnd: "%",
  min: 0,
  max: 100,
  step: 1,
  value: 0
});

// Tax rate
composer.numberInput("taxRate", {
  question: "Tax rate",
  unitEnd: "%",
  min: 0,
  max: 50,
  step: 0.5
});

Time & Speed

Various time and speed units:

// Duration in hours
composer.numberInput("duration", {
  question: "Duration",
  unitEnd: "hours",
  min: 0,
  step: 0.5
});

// Age in years
composer.numberInput("age", {
  question: "Age",
  unitEnd: "years",
  min: 0,
  max: 150
});

// Speed
composer.numberInput("speed", {
  question: "Maximum speed",
  unitEnd: "mph",
  min: 0,
  max: 200
});

Decimal Precision

Use the step parameter to control decimal precision.

// Whole numbers only
step: 1

// One decimal place
step: 0.1

// Two decimal places (currency)
step: 0.01

// Three decimal places
step: 0.001

Whole Numbers

composer.numberInput("quantity", {
  question: "Quantity",
  min: 1,
  step: 1  // No decimals
});

Validation

Range Validation

Set minimum and maximum values:

composer.numberInput("rating", {
  question: "Rate from 1 to 5",
  required: true,
  min: 1,
  max: 5,
  description: "Enter a number between 1 and 5"
});

The browser will prevent:

• Values below min
• Values above max
• Non-numeric input

Positive Numbers Only

Prevent negative values:

composer.numberInput("amount", {
  question: "Amount",
  unit: "$",
  min: 0,  // No negative values
  step: 0.01
});

Required vs Optional

// Required - user must enter a value
composer.numberInput("age", {
  question: "Your age",
  required: true,
  min: 18
});

// Optional - can be left empty
composer.numberInput("referralCode", {
  question: "Referral code (optional)",
  min: 1000,
  max: 9999,
  placeholder: "Enter 4-digit code"
});

Common Patterns

Price/Budget

composer.numberInput("budget", {
  question: "Your budget",
  unit: "$",
  min: 0,
  max: 1000000,
  step: 100
});

Age

composer.numberInput("age", {
  question: "Your age",
  min: 18,
  max: 120,
  required: true
});

Quantity

composer.numberInput("qty", {
  question: "Quantity",
  min: 1,
  max: 999,
  value: 1,
  step: 1
});

Percentage

composer.numberInput("percent", {
  question: "Percentage",
  unitEnd: "%",
  min: 0,
  max: 100,
  step: 1
});

Best Practices

Set appropriate ranges

Always set realistic min and max values:

// Good - reasonable age range
min: 0, max: 120

// Good - positive prices
min: 0

// Good - rating scale
min: 1, max: 5

Use appropriate step values

Match the step to your use case:

// Whole numbers (quantity, age)
step: 1

// Currency (USD, EUR)
step: 0.01

// Percentage in increments
step: 5  // 0, 5, 10, 15...

// Precise measurements
step: 0.1

Choose the right unit placement

Use unit (prefix) for:

• Currency symbols: $, €, £, ¥

Use unitEnd (suffix) for:

• Measurement units: kg, m, cm, L
• Time units: hours, days, years
• Percentages: %
• Rates: mph, km/h

Provide helpful descriptions

Clarify the expected input:

description: "Must be between 1 and 100"
description: "Enter amount in US dollars"
description: "Increments of 5 only"
description: "Maximum 2 decimal places"

Set sensible defaults

Use value for common starting points:

// Quantity defaults to 1
value: 1

// Common percentage
value: 10

// Standard rate
value: 100

Return Value

Returns a string containing the Forms.md markup for the number input field.

Submitted value: Numeric value (number type), e.g., 42, 19.99, 75.5

Related Methods

textInput

Text input for non-numeric values

ratingInput

Visual rating with stars or hearts

opinionScale

NPS-style numeric scale