useCounter

React state hook that tracks a numeric value

useCounter manages an integer counter with built-in inc, dec, set, and reset functions. It returns a tuple of [current, set, inc, dec, reset]. You can optionally specify max and min bounds; the counter will be clamped to stay within those limits. The initial value defaults to 0 and can be a number or a function returning a number.

When to Use

• Implementing quantity selectors, pagination controls, or stepper inputs
• Tracking scores, votes, or item counts with enforced minimum/maximum boundaries
• Any numeric state that benefits from dedicated increment, decrement, and reset actions

Notes

• Bounded values: When max or min is provided, the counter is clamped after every operation. Setting a value outside the bounds will be silently adjusted.
• SSR-safe: Uses only React state internally with no browser API dependencies.
• See also useCycleList for cycling through a fixed list of items rather than an open numeric range.

Usage

function Demo() {
  const [current, set, inc, dec, reset] = useCounter(10, 100, 1);

  return (
    <div>
      <p>{current} max: 100; min: 1;</p>
      <div>
        <button
          type="button"
          onClick={() => {
            inc();
          }}
          style={{ marginRight: 8 }}
        >
          inc()
        </button>
        <button
          type="button"
          onClick={() => {
            dec();
          }}
          style={{ marginRight: 8 }}
        >
          dec()
        </button>
        <button
          type="button"
          onClick={() => {
            set(3);
          }}
          style={{ marginRight: 8 }}
        >
          set(3)
        </button>
        <button type="button" onClick={reset} style={{ marginRight: 8 }}>
          reset()
        </button>
      </div>
    </div>
  );
};

API

useCounter

Returns

readonly [number, (newState: number | ((prev: number) => number) | (() => number)) => void, (delta?: number | undefined) => void, (delta?: number | undefined) => void, () => void]: A tuple with the following elements:

• The current value of the counter.
• A function to set the state of the counter. It can accept a number or a function that returns a number.
• A function to increment the counter. It optionally accepts a number to increment the counter by, defaulting to 1.
• A function to decrement the counter. It optionally accepts a number to decrement the counter by, defaulting to 1.
• A function to reset the counter to its initial value.

Arguments