Components

NumberInput

The NumberInput component is similar to the Input, but has controls for incrementing or decrementing.

Import

NumberInput: The wrapper that provides context and logic to the components.
NumberInputField: The input field itself.
NumberInputStepper: The wrapper for the input's stepper buttons.
NumberIncrementStepper: The button to increment the value of the input.
NumberDecrementStepper: The button to decrement the value of the input.

import {
  NumberInput,
  NumberInputField,
  NumberInputStepper,
  NumberIncrementStepper,
  NumberDecrementStepper,
} from '@outfitio/outkit';

Usage

The NumberInput is composed of smaller components to give you control of the styling of each part.

Setting a minimum and maximum value

Pass the min prop or max prop to set an upper and lower limit for the input. By default, the input will restrict the value to stay within the specified range.

Setting the step size

Pass the step prop to change the step size when you increment or decrement the value. By default, the value is rounded to match the number of decimals in the step.

Adjusting the precision of the value

In some cases, you might need the value to be rounded to specific decimal points. Simply pass the precision prop and set it to the number of decimal points.

Showing the numeric keyboard on mobile

By default the NumericInputField is of type text, hence displaying a full keyboard on mobile devices. If you want to display a numeric keyboard, add type="number" to the NumberInputField input, like so:

Clamp value when user blurs the input

In most cases, users can type custom values in the input field. If the typed value is greater than the max, the value is reset to max when the user blurs out of the input. To disable this behavior, pass clampValueOnBlur and set to false.

In this example, try to type a value greater than the max. It won't reset the value on blur.

Allowing out of range values

In some scenarios, you might not want to block out of range values. Simple pass keepWithinRange and clampValueOnBlur and set them to false to support this use case.

The NumberInput will be set isInvalid to true internally when the value is out of range. Out of range means that the value is great than max or less than min.

Changing the size of the input

Use the size prop to change the size of the button. You can set the value to sm (32px), md (default, 40px), or lg (48px).

Changing the styles

You can change the style of any part of the components using style props. You can also change the icons used in the steppers

Combining it with a Slider

The NumberInput can also be combined with a Slider. Here's an example of how to do that.

Accessibility

The input has role set to spinbutton to denote that users are to select from a range of discrete values using an up and down arrows on the keyboard.
The input has aria-valuemin set to the minimum value allowed for the spinbutton.
The input has aria-valuemax set to the maximum value allowed for the spinbutton.
The input has aria-valuenow set to the current value of the input.
The custom spinner (up and down buttons) havearia-hidden set to true to make them invisible to screen readers.
When you hit the ⬆ or ⬇ key, the input value will be increased or decreased by step
Holding down Shift and pressing ⬆ or ⬇ will update the value by 10 * step
Holding down Ctrl or ⌘, and pressing ⬆ or ⬆ will update the value by 0.1 * step
Long press the Up and down stepper buttons will update the value at intervals.

Best Practice

Like all inputs, number inputs should:

Be used within the Form Control component to provide an accessible label and error states.
Be clearly labeled so that it is obvious to users what they should enter into the field
Be labeled as 'Optional' if the input is not required

Props

NumberInput Props

NumberInput composes Flex with some additional props listed below.

Name	Type	Default	Description
`value`	`number`		The value of the input for controlled usage. Should be less than `max` and greater than `min`
`defaultValue`	`number`		The initial value of the input. Should be less than `max` and greater than `min`
`onChange`	`(value: number) => void`		The callback fired when the value changes
`min`	`number`	`-Infinity`	The maximum value of the input
`max`	`number`	`Infinity`	The minimum value of the input
`step`	`number`	`1`	The step used to increment or decrement the value
`precision`	`number`		The number of decimal points used to round the value
`isReadOnly`	`boolean`		If `true`, the input will be in readonly mode
`isInvalid`	`boolean`		If `true`, the input will have `aria-invalid` set to `true`
`isDisabled`	`boolean`		If `true`, the input will be disabled
`keepWithinRange`	`boolean`	`true`	If `true` and you use the stepper or up/down arrow keys, the value will not exceed the `max` or go lower than `min`
`clampValueOnBlur`	`boolean`	`true`	If `true` and the value is greater than `max`, the value will be reset to `max`
`focusInputOnChange`	`boolean`	`true`	If `true`, the input will be focused as you increment or decrement the value with the stepper
`getAriaValueText`	`(value: number) => string`	`true`	It is used to set the `aria-valuetext` property of the input

NumberInputField Props

NumberInput composes Input so you can pass all Input props.

NumberInputStepper Props

NumberInputStepper composes Flex so you can pass all Flex props.

NumberDecrementStepper and NumberIncrementStepper Props

NumberDecrementStepper and NumberIncrementStepper composes the PseudoBox props so you can pass all PseudoBox props.