NumericStepper

NumericSteppers represent a control for regular numerical input, where you expect the user to modify it by a few incremental steps.

Examples

Tone of voice

The NumericStepper tone of voice is either neutral (default) or critical, and is adjustable with the tone prop.

<Stack direction="row" space="$l">
  <NumericStepper
    value={10}
    minValue={0}
    maxValue={10}
    onChange={() => null}
    helperText="Helper text"
    label="numeric-stepper"
  />
  <NumericStepper
    value={10}
    minValue={0}
    maxValue={10}
    tone="critical"
    onChange={() => null}
    criticalText="Critical text"
    label="numeric-stepper"
  />
</Stack>

Step Multiplier

The NumericStepper has two buttons: one to increment the value and the other to decrement. By default, you can increase or decrease the value one by one, but you can also set a step, so the value will increase or decrease according to the multiplier defined.

function Example() {
  const [value, setValue] = React.useState(0)

  return (
    <NumericStepper
      value={value}
      step={5}
      helperText="Helper Text"
      label="numeric-stepper"
      onChange={(event) => setValue(event.value)}
    />
  )
}

Minimum and Maximum limits

You can define two limits so that the value is never less than the minimum or greater than the maximum. If you reach one of these limits, the buttons for increasing and decreasing the value will be disabled. To use these variations the minValue and maxValue properties should have a value defined.

function Example() {
  const [value, setValue] = React.useState(0)

  return (
    <NumericStepper
      value={value}
      minValue={0}
      maxValue={4}
      onChange={(event) => setValue(event.value)}
      label="stepper number"
    />
  )
}

Helper Text

You can add a helper text to indicate the proper way to fill in the numeric stepper. To use this variation, the helperText property should have a value defined.

function Example() {
  const [value, setValue] = React.useState(0)

  return (
    <NumericStepper
      value={value}
      helperText="Helper Text"
      label="numeric-stepper"
      onChange={(event) => setValue(event.value)}
    />
  )
}

Disabled

It means that the user will not be able to add any input value to the NumericStepper. To use this variation, the disabled property should have a true value.

<NumericStepper
  value={0}
  onChange={() => {}}
  disabled
  label="numeric-stepper"
/>

Usage

import { NumericStepper } from '@vtex/admin-ui'

function Example() {
  const [value, setValue] = React.useState(0)

  return (
    <NumericStepper
      value={value}
      helperText="Helper Text"
      label="numeric-stepper"
      onChange={(event) => setValue(event.value)}
    />
  )
}

State

You can use the properties value, and onChange to handle value changes. You also can control the tone property to indicate if it is a valid input or not. Note that the onChange represents a function with an object { value: number } as a parameter. Check the example below.

function Example() {
  const [value, setValue] = React.useState(0)

  return (
    <NumericStepper
      value={value}
      helperText="Helper Text"
      tone={value === 5 ? 'critical' : 'neutral'}
      criticalText="Value cannot be 5!"
      label="numeric-stepper"
      onChange={(event) => setValue(event.value)}
    />
  )
}

Props

Name	Type	Description	Required	Default
value	number	Displayed value	✅	-
onChange	({value: number}) => void	Change handler	✅	-
label	string	Input label	✅	-
minValue	number	Min value accepted	🚫	-10e9
maxValue	number	Max value accepted	🚫	10e9
disabled	boolean	Whether its disabled or not	🚫	false
tone	neutral, critical	Tone of voice	🚫	neutral
criticalText	string	Error message	🚫	-
helperText	string	Helper text message	🚫	-
step	number	Increment and decrement multiplier value	🚫	1

Do’s

1. Always use a default value. If you do not know which one to use, pick 1. This way the user is not forced to type something and then click the buttons.
2. The lean mode is intended to be used on lists, that have a high density of content, and where being able to type the number is not important. It is especially useful in mobile contexts or cramped containers.
3. Do not use for big numbers. Steppers make more sense for small numbers that might be adjusted with a few clicks.
4. Add the units, whenever applicable. Ex. kg, m², days, etc.

👉 For UX Writing guidelines, access https://uxwriting.vtex.com

• Examples
  • Tone of voice
  • Step Multiplier
  • Minimum and Maximum limits
  • Helper Text
  • Disabled