Helsinki Design System
Helsinki Design System
Getting started
Tutorials
Guidelines
Visual assets
Design tokens
Components
OverviewAccordionButtonCardCheckboxDate inputDialogDropdownFieldsetFooterIconKorosLoading spinnerLogoNavigationNotificationNumber inputPrinciplesAccessibilityUsage and variationsDemos & APIPassword inputPhone inputRadio buttonSearch inputSelection groupStatus labelTabsTagText fieldsTime inputToggle buttonTooltip
Patterns
About
Contributing
Resources

Number input

DraftAccessible

A number input allows the user to enter numeric values. It also features optional steppers for increasing or decreasing the value by a set amount.

Principles

  • A label should always be provided with a number input.
    • Make sure that the label is clear and concise. The user should immediately understand what number they are supposed to input.
  • HDS Number input also supports displaying an unit for the number. Displaying the unit is not mandatory. Only use it when you think it will help the user.
    • Display the unit for SI units (such as meters) and currencies.
    • The unit does not need to be displayed when it is self-evident for the user, such as in "Number of people"
  • It is recommended to give the number input a default value. Placeholders should be avoided in number inputs.
  • HDS Number input supports visual steppers that can be set to increase and decrease the number value by a set amount.
    • Steppers can be used when changes to the value are small or when they are intuitive to the user (e.g. from 0 to 100 with steps of 10).
    • You should not use steppers when large value changes are expected.

Accessibility

  • HDS number input allows the user to input the date manually without using stepper actions. Whenever you require the user to input numbers, you should also allow manual input.
  • If steppers are used, provide descriptive aria labels for both increase and decrease actions by using minusStepButtonAriaLabel and plusStepButtonAriaLabel props.
  • If the number needs to follow a specific format, remember to specify it in the assistive text.
  • Placeholders in number inputs should be avoided. Different screen readers announce placeholders in different ways. It can be very difficult for a screen reader user to differentiate the placeholder from the actual value.

Usage and variations

Default number input

Default HDS Number input comes without stepper. The number is always inputted manually. Using this over a text input is still helpful since it has a type=number to aid screen readers and mobile keyboards.

When applicable, a unit can be set for the input by using the unit prop.

Assistive text
Assistive text

Core code example:

<div class="hds-text-input">
<label for="input" class="hds-text-input__label">
Total compensation (€)
<span class="hds-text-input__required">*</span>
</label>
<div class="hds-text-input__input-wrapper">
<input id="input" value="1000" class="hds-text-input__input" type="number" placeholder="Placeholder" required />
</div>
<span class="hds-text-input__helper-text">Assistive text</span>
</div>

React code example:

<NumberInput
helperText="Assistive text"
label="Total compensation"
unit=""
defaultValue={1000}
/>
<NumberInput
disabled
helperText="Assistive text"
label="Total compensation"
unit=""
defaultValue={1000}
/>

Number input with steppers

Steppers can be enabled via providing a step property. Use this variant when value changes are small and you can determine logical amounts for an increase and a decrease step.

Assistive text

Core code example (functionality differs from the React one):

<div class="hds-text-input">
<label for="input" class="hds-text-input__label">
Total compensation (€)
<span class="hds-text-input__required">*</span>
</label>
<div class="hds-text-input__input-wrapper">
<input id="input" value="1000" class="hds-text-input__input" type="number" step="1" placeholder="Placeholder" required />
</div>
<span class="hds-text-input__helper-text">Assistive text</span>
</div>

React code example:

<NumberInput
helperText="Assistive text"
label="Number of attendees"
minusStepButtonAriaLabel="Decrease by one"
plusStepButtonAriaLabel="Increase by one"
step={1}
defaultValue={5}
/>

Number input with min and max values

Steppers can be enabled by providing a step property. Use this variant when value changes are small and you can determine logical amounts for an increase and a decrease step.

If your input has special requirements, it is a good practice to describe them in the assistive text.

At least 3 attendees are required

Core code example (functionality differs from the React one):

<div class="hds-text-input">
<label for="input" class="hds-text-input__label">
Number of attendees
<span class="hds-text-input__required">*</span>
</label>
<div class="hds-text-input__input-wrapper">
<input id="input" value="1000" class="hds-text-input__input" type="number" step="1" min="3" max="99" placeholder="Placeholder" required />
</div>
<span class="hds-text-input__helper-text">Assistive text</span>
</div>

React code example:

<NumberInput
helperText="At least 3 attendees are required"
label="Number of attendees"
min={3}
max={99}
minusStepButtonAriaLabel="Decrease by one"
plusStepButtonAriaLabel="Increase by one"
step={1}
defaultValue={3}
/>

Demos & API

Core

Number input in hds-core

React

Number input in hds-react

NumberInput API