NumberInput

Usage

Number Input component allows users to input numerical formats in the field. They are usually found within a Form Group but can also be standalone, part of Modal or Card. It is recommended to use this component always with the Label.

Types

Number Input component can have the following properties/types:

With Label or Without Label. We use Form Label component here. When it is With Label, the Form Label component controls the placement of label relative to the Number Input component; either Above or Left. Label Right option of Form Label is disabled for Number Input component.

INFO

In Figma however, the Label placement is controlled by the Number Input component itself, due to the way Figma works with nested components

With or Without Help Text (of type Info) passed as an object property, following the Help Text properties declaration
With or Without Validation. If there is a validation in the specific Text Input component then the component can have either of these three validation statuses: None (default), Validated and Invalid. Validated and Invalid statuses use Help Text to display a descriptive message on the status of validation. Below you can find more guidelines on how to present validation messages. If a Number Input component is With Help Text (of type Info) and it is also With Validation then Validation related status display within a Help Text overrides the original Help Text of the type Info, which means validation message has more weight than the Help Text of type Info. Depending on the use case, validation can happen either after active submission of the form by user or when user clicks elsewhere after typing in the Number Input.

Distinction between input component level validation and a form level validation

There are two ways user input can be validated: Validation on a form level or in each individual input component.

Validation on the input component level happens per the specific input component such as Number Input and its validation message (Help Text component) is displayed in the context of the input element.

Validation on a Form Group level happens when several elements inside a Form Group can be checked at the same time and a common validation message can be displayed (such as in the examples of Login forms, where a single ‘Invalid’ message is displayed for either/both Login name and Password invalidity). In such cases Help Text is used as a validation message of the whole Form Group and is placed detached from the input components. However, each input component that is affected, changes its status to Invalid or Validated accordingly, but without individual validation message (Help Text components) per each component.

Anatomy and Behavior

Container - is a clickable area of the component that enables and contains user’s input
Label - is the atom component - Form Label. Form label is a word or a phrase that describes what is the requested input from the user. It can be either at the left side or above the container. Form Label should be always visible, short and clear. Form Label shouldn’t be truncated or take up multiple lines.
Number Input- It can be a placeholder text that can hold an example input value that transforms into user input once user starts typing. Avoid using placeholder to communicate critical information because this approach is not accessible. Use labels or helper text to describe the purpose of the field and how to use it. The number input should not be longer then the width of the container allows. Text does not wrap down and the container does not grow in size.
Help text - is a nested component - Help Text. It is an optional property of the Number Input component. It conveys additional guidance about the input field. Help Text can take up to two lines. If Number Input component has a Validation property, Help Text can be used as feedback on the value input by user, informing if the input is Valid or Invalid with appropriate icons and color coding.
- Invalid - Help text mush show error message when user needs to be informed of wrong input or lack of input. If only one error is possible, error text describes how to avoid the error. If multiple errors are possible, error text describes how to avoid the most likely error
- Validated - If an input is validated then Help text must communicate it with corresponding message and color coding. After the input has been validate, changes made by user in the Text Input restore the component’s default state until user confirms the input by actively saving, submitting or clicking outside the Text Input depending on use case
Input Number Unit - The Number Unit represents the numerical value or quantity of the field (for example: kg, m, sq. m, etc.). This value is defined by the development team in code. A property ‘Unit’ is attached to the Number Input component in code and reflects in the UI

States

Default Number Input can have :hover, :focus, Disabled states. Once user clicks on the Number Input (:active) it gets activated to allow user input and it is the same state as :focus.
Invalid Number Input can only have :hover state. Once user clicks on Number Input it resets to default and is in :focus state.
Validated Number Input can only have :hover state. Once user clicks on Number Input it resets to default (no validation) state and is in :focus state.

Gaps and Sizes

Container width: Fill container (element adapts to its parent container width) (min. width is 5XL)
Container height: XLplus (Fixed)
Gap between Form Label and container - Label Above variant: 2XS
Gap between container and help text: 2XS
Content vertically center aligned.
Gap between Placeholder/Input number and unit : max: space between, min: S
Container padding: S

INFO

Number Input component’s width scales responsively to adapt to the viewport and screen size. Therefore maximum and minimum allowed width should be adjusted according to the use case in every application

Tokens

SCSS Variable

Value

$numberInput-bgColor

--color-grey-93

$numberInput-unit-color

--color-grey-25

$numberInput-placeholder-color

--color-grey-70

$numberInput-inputNumber-color

--color-grey-25

$numberInput-outline-color--focus

--color-azure-45

$numberInput-outline-color--invalid

--color-red-50

$numberInput-outline-color--locked

--color-grey-86

$numberInput-placeholder-color--locked

--color-grey-80

$numberInput-inputNumber-color--locked

--color-grey-70

$numberInput-unit-color--locked

--color-grey-70

$numberInput-boxShadow

--debossed-1--grey-95

$numberInput-boxShadow--hover

--debossed-2--grey-95

$numberInput-cornerRadius

--gutter-2xs

$numberInput-padding

--gutter-s

$numberInput-text: %numbers

Properties

export type Unit =
  | 'gr'
  | 'kg'
  | 's'
  | 'N'
  | 'N/mm<sup>2</sup>'
  | 'kN'
  | 'kN/m'
  | 'kN/m<sup>3</sup>'
  | 'm'
  | 'cm'
  | 'mm'
  | '°';

export type NumberInputProps =
  & Omit<FormLabelOptionalProps, 'disabled'>
  & TooltipProps
  & {
    modelValue: number | null;
    disabled?: boolean;
    placeholder?: string;
    fractionDigits?: number;
    step?: number;
    unit?: Unit | string;
    range?: [number | null, number | null];
    helpText?: HelpTextProps['text'];
    validation?: HelpTextProps['category'];
  };

export type FormLabelCategory = "compact" | "default";
export type FormLabelPosition = "labelLeading" | "labelTrailing" | "labelAbove";

export interface FormLabelProps extends TooltipProps {
  label?: string;
  tooltip?: string;
  labelCategory: FormLabelCategory;
  labelPosition: FormLabelPosition,
  disabled?: boolean;
  required?: boolean;
  clickableLabel?: boolean;
}

export type TooltipPosition = 'top-left' | 'top-right' | 'top-center' | 'bottom-left' | 'bottom-right' | 'bottom-center';

export interface TooltipProps {
  tooltip?: string;
  tooltipPosition?: TooltipPosition;
  tooltipLines?: number;
}

Configurations

Number Input
Variety	Normal	Disabled
Normal
Units	mm	mm
Help Text Info
Help Text Invalid
Help Text Validated

Number Input
Variety	Small	Medium	Big
Label Leading	Label leading* kg	Label leading* kg	Label leading* kg
Label Above	Label above* gr	Label above* gr	Label above* gr

Developer Notes

NOTE

Change Event (@change): Triggered when the input changes. The event sends the updated modelValue as payload.
Blur Event (@blur): Triggered when the input is unfocused.
Keydown Event (@keydown): Triggered when any key from the keyboard is pressed while component is focused.

Functionality

Once a NumberInput element is in :active state, you can use your keyboard to manipulate the input, too.

Arrow up: increase input by 1 * step
Arrow down: decrease input by 1 * step
Ctrl + Arrow *: increase/decrease by 10 * step
Ctrl + Shift + Arrow *: increase/decrease by 100 * step

You can also specify ranges for the allowed input values. When inputting values out of bounds, an invalid help text will be displayed, indicating the corresponding overflow.

NumberInput ​

Usage ​

Types ​

Distinction between input component level validation and a form level validation ​

Anatomy and Behavior ​

States ​

Gaps and Sizes ​

Tokens ​

Properties ​

Configurations ​

Developer Notes ​

Functionality ​

NumberInput

Usage

Types

Distinction between input component level validation and a form level validation

Anatomy and Behavior

States

Gaps and Sizes

Tokens

Properties

Configurations

Developer Notes

Functionality