use-stepper

React hook to manage a numeric stepper/spinbutton

The problem

A numeric stepper or "spinbutton" (decrement button, input, increment button) is deceptively non-trivial to implement. You have to manage the minimum, the maximum, the input itself displaying the current value (conceptually numeric, but ultimately a string in HTML), allowing a user to type freely and hopefully arrive at a valid number (e.g. "-" is NaN but you have to let them type it so they can get to "-4", so simply parsing their input as a number is insufficient), interpreting the input's value on blur, etc.

This solution

This React hook manages all this for you so you only have to worry about the styling. It returns the current value, functions for manual value manipulation, and a collection of prop getters to spread across your form elements to make it all work together. It also includes the ability to provide your own custom state reducer to enable ultimate control over what actions like "increment", "decrement", "coerce", etc. mean in your application.

Table of Contents

• Installation
• Usage
• Basic Options
  • defaultValue
  • step
  • min
  • max
• Advanced Options
  • enableReinitialize
  • stateReducer
    • Example
• Return Value
  • prop getters
  • state
  • setters
• Other Solutions
• License

Installation

Using npm:

npm install use-stepper # or, with yarn: yarn add use-stepper

This package also depends on react 16.8.0 or newer. Please make sure you have that installed as well.

Usage

import { useStepper } from 'use-stepper';

function MyStepper() {
  const { getFormProps, getInputProps, getIncrementProps, getDecrementProps } = useStepper();

  return (
    <form {...getFormProps()}>
      <button {...getDecrementProps()}>-</button>
      <input {...getInputProps()} />
      <button {...getIncrementProps()}>+</button>
    </form>
  );
}

Basic Options

The hook accepts an options object as its only parameter. The entries for the basic options are as follows:

defaultValue

number | optional, default: 0

The initial value and the value to use as a fallback upon invalid manual input.

step

number | optional, default: 1

The amount by which to increment or decrement the current value.

min

number | optional, default: -Number.MAX_VALUE

The minimum value allowed.

max

number | optional, default: Number.MAX_VALUE

The maximum value allowed.

Advanced Options

enableReinitialize

boolean | optional, default: false

Controls whether the current value (if unchanged) will update to the new default if defaultValue changes.

stateReducer

function(state: object, action: object): object | optional

Changes to the state of the hook are applied using React's built-in useReducer hook. This function replaces the default reducer implementation, which allows you to author your own logic to execute when an action is dispatched. This gives you ultimate control in the event you wish to constrain the value or otherwise modify the default behavior. It gives you the current state and the action to execute, and you return the new state.

• state: the current state of the hook
• action: the action to execute

State is just an object with a value key (note: value is a string, so it should be converted to a number before performing mathematical operations on it).

Actions have a type field and an optional payload field. The possible action types are discoverable through useStepper.actionTypes (e.g. useStepper.actionTypes.increment). The default reducer is also available at useStepper.defaultReducer in case you want to defer to the default implementation in some cases (e.g. for the default/unhandled action, perhaps).

Example

Constrain the stepper to only use whole numbers:

function IntegerStepper({ min, max, defaultValue }) {
  function validValueClosestTo(desiredNumericValue) {
    return String(Math.min(max, Math.max(desiredNumericValue, min)));
  }

  function integerReducer(state, action) {
    const integerValue = parseInt(state.value, 10);
    switch (action.type) {
      case useStepper.actionTypes.increment: {
        return { value: validValueClosestTo(integerValue + 1) };
      }
      case useStepper.actionTypes.decrement: {
        return { value: validValueClosestTo(integerValue - 1) };
      }
      case useStepper.actionTypes.coerce: {
        if (Number.isNaN(integerValue)) {
          return { value: String(defaultValue) };
        }
        const newValue = validValueClosestTo(integerValue);
        if (newValue !== state.value) {
          return { value: newValue };
        }
        return state;
      }
      default:
        return useStepper.defaultReducer(state, action);
    }
  }

  const { getInputProps, getIncrementProps, getDecrementProps } = useStepper({
    min,
    max,
    defaultValue,
    stateReducer: integerReducer,
  });

  return (
    <>
      <button {...getDecrementProps()}>-</button>
      <input {...getInputProps()} />
      <button {...getIncrementProps()}>+</button>
    </>
  );
}

Return Value

The hook returns an object with the following shape:

key	type	category
getFormProps	function	prop getter
getInputProps	function	prop getter
getIncrementProps	function	prop getter
getDecrementProps	function	prop getter
value	string	state
increment	function	setter
decrement	function	setter
setValue	function	setter

prop getters

These functions are used to apply props to the elements that you render. This gives you maximum flexibility to render what, when, and wherever you like. You call these on the element in question (for example: <input {...getInputProps()})). It's advisable to pass all your props to that function rather than applying them on the element yourself to avoid your props being overridden (or overriding the props returned). For example: getInputProps({ onChange: myChangeHandler }).

key	type	description
getFormProps	function({})	returns the props you should apply to the form element for submit handling
getInputProps	function({})	returns the props you should apply to the input element (includes value)
getIncrementProps	function({})	returns the props you should apply to the increment button element
getDecrementProps	function({})	returns the props you should apply to the decrement button element

state

These are the values that represent the internal state of the hook.

key	type	description
value	string	the current value of the stepper

setters

These functions are exposed to provide manual manipulation of the internal value.

key	type	description
increment	function()	increments the value
decrement	function()	decrements the value
setValue	function(str)	sets the value (note: the argument passed will be coerced to a valid value within the specified range or fall back to the default value if not a valid number)

Other Solutions

• @zag-js/number-input is a more full-featured alternative driven by state machines and maintained by the team behind the popular Chakra UI project.
• react-stepper-primitive by Andrew Joslin was the prime source of inspiration for this hook.

If you know of any others, please send a pull request to add them here.

License

MIT