useCounter

useCounter

Manage numeric state with built-in min and max bounds, adjustable step increments, and fully clamped limits. This hook eliminates the boilerplate of manually validating numeric ranges before updating state.

Usage Examples

Basic

A simple counter using the default step of 1.

import { useCounter } from "react-hook-lab";

function Counter() {
  const { count, increment, decrement, reset } = useCounter(0);

  return (
    <div>
      <p>Current Count: {count}</p>
      <button onClick={decrement}>-</button>
      <button onClick={increment}>+</button>
      <button onClick={reset}>Reset</button>
    </div>
  );
}

Common

Enforcing a minimum and maximum limit, perfect for pagination or bounded input fields.

import { useCounter } from "react-hook-lab";

function Pagination() {
  // Clamps the count strictly between 1 and 10
  const { count: page, increment: next, decrement: prev } = useCounter(1, { 
    min: 1, 
    max: 10 
  });
  
  return (
    <div>
      <button onClick={prev} disabled={page === 1}>Previous</button>
      <span>Page {page} of 10</span>
      <button onClick={next} disabled={page === 10}>Next</button>
    </div>
  );
}

Advanced

Using custom steps and directly overriding the count with set while still enforcing boundaries.

import { useCounter } from "react-hook-lab";

function VolumeControl() {
  const { count: volume, increment: volUp, decrement: volDown, set: setVolume } = useCounter(50, { 
    min: 0, 
    max: 100, 
    step: 5 
  });

  return (
    <div>
      <p>Volume: {volume}%</p>
      <button onClick={volDown}>Vol -5</button>
      <button onClick={volUp}>Vol +5</button>
      <button onClick={() => setVolume(100)}>Max Volume</button>
      
      {/* If the user inputs 999, it will automatically clamp down to 100 */}
      <input 
        type="number" 
        value={volume} 
        onChange={(e) => setVolume(Number(e.target.value))} 
      />
    </div>
  );
}

API Reference

Parameters

• initialValue (Optional)
  • Type: number
  • Default: 0
  • Description: The initial starting value for the counter.
• options (Optional)
  • Type: UseCounterOptions
  • Description: Configuration object to enforce ranges and steps.

export interface UseCounterOptions {
  min?: number;  // Default: Number.MIN_SAFE_INTEGER
  max?: number;  // Default: Number.MAX_SAFE_INTEGER
  step?: number; // Default: 1
}

Return Object

Returns an object of type UseCounterReturn containing:

• count (number): The current numeric state.
• set ((value: number) => void): Clamps the given value between min and max and sets the state.
• increment (() => void): Increases the count by step (up to max).
• decrement (() => void): Decreases the count by step (down to min).
• reset (() => void): Resets the count strictly to the initialValue.

Core Working

Under the hood, useCounter manages the numeric state using React's useState. All modifier functions internally route through a memoized clamp function. When increment, decrement, or set is invoked, the hook checks Math.max(min, Math.min(max, newValue)). This guarantees that your count variable will never fall outside the defined bounds, regardless of the calculation or manual input string.