Skip to main contentCarbon Design System

Number input

Number input lets users enter a numeric value and incrementally increase or decrease the value with a two-segment control.

Overview

Number inputs are similar to text inputs, but are used to specify only a numeric value. Number inputs incrementally increase or decrease the value with a two-segment control. Number input reduces input efforts for adjusting small values.

number input image

When to use

  • The user needs to input a numeric value
  • Adjusting small values when increasing or decreasing them requires only a few clicks
  • When users may not know exact values and only want to change the values that are relative to its current state

When not to use

  • It is best practice not to use number input if large value changes are expected. For example, when the value sets from 1 to 30, number input is not a great option because it requires many clicks to reach 30. In this case, use slider when numeric values are large or when there is a wide range of numeric options.
  • It is also best to avoid number input for continuous variables such as prices, distances, lengths, or human heights. When the exact value is important to specify within a wide range, use text input instead.

Live demo

CodeSandbox React Angular Vue Web Components 


    <NumberInput

      helperText="Optional helper text"

      id="tj-input"

      invalidText="Number is not valid"

      label="Number input label"

      max={100}

      min={0}

      step={10}

      value={50}

    />

Formatting

Anatomy

Anatomy of a default number input
  1. Label: Text that informs the user about the content they need to enter in the field. It is required unless you get an approved accessibility exemption.
  2. Numeric value: The value changes when user enters a value into the field or uses the subtract or add controls.
  3. Helper text: Assistive text that can provide additional aid or context to the user. Often used to explain the correct data format.
  4. Field: The container in which a user enters data.
  5. Subtract icon: This icon triggers decremental values.
  6. Add icon: This icon triggers incremental values.
  7. Status icon: Indicates the state of the number input, either error or warning.
  8. Error or Warning text: It replaces the helper text when an error or warning state appears.

Styling

There are two styles of number inputs, default and fluid. They share the same functionality but look visually different, influencing where to use them.

StyleAppearanceUse case
DefaultA traditional style where the label is positioned outside and above the input field.Use when white space is needed between input components or in productive moments where space is at a premium, and smaller components are needed.
FluidAn alternative style where the label is placed inside of the input field and is stacked inline with the user input text.Use in expressive moments, fluid forms, contained spaces, or attached to complex components, like a toolbar.
An example of a default and fluid number input

A default style input is shown on the left and fluid style is on the right.

Sizing

Default input heights

Number input has three sizes default input heights: small, medium, and large. The width varies in size based on content, layout, and design.

SizeHeight (px/rem)Use case
Small (sm)32 / 2Use when space is constricted or when placing a number input in a form that is long and complex.
Medium (md)40 / 2.5This is the default size and the most commonly used size. When in doubt, use the medium size.
Large (lg)48 / 3Use when there is a lot of space to work with. The large size is typically used in simple forms or when a number input is placed by itself on a page.