StateBeginnerFully SSR-safehooks/state/useCounter.ts

useCounter

Numeric counter with min, max, and step.

Import

TypeScript
import { useCounter } from '@/hooks';

API

Signature

useCounter(initial?, { min, max, step }) → [count, { inc, dec, set, reset }]

When to use

Use useCounter instead of re-implementing the same pattern in multiple components.

SSR / Next.js

Fully SSR-safe. Pure React state.

Live playground

Edit the example and see it run against the real @/hooks package in this app.

Live playgroundEdit · run with real @/hooks · useCounter
Editor
function Qty() {
  const [count, { inc, dec, reset, set }] = useCounter(1, {
    min: 1,
    max: 99,
    step: 1,
  });

  return (
    <div>
      <button onClick={() => dec()}>-</button>
      <span>{count}</span>
      <button onClick={() => inc()}>+</button>
      <button onClick={() => set(10)}>Set 10</button>
      <button onClick={reset}>Reset</button>
    </div>
  );
}
Preview

Implementation source

Full library source for useCounter — copy into your project when you are not installing a package yet.

hooks/state/useCounter.ts
import { useCallback, useState } from 'react';

export interface UseCounterOptions {
  min?: number;
  max?: number;
  step?: number;
}

export interface UseCounterActions {
  inc: (delta?: number) => void;
  dec: (delta?: number) => void;
  set: (value: number | ((prev: number) => number)) => void;
  reset: () => void;
}

export type UseCounterReturn = [number, UseCounterActions];

function clamp(value: number, min?: number, max?: number): number {
  let next = value;
  if (typeof min === 'number') next = Math.max(min, next);
  if (typeof max === 'number') next = Math.min(max, next);
  return next;
}

/** Numeric counter with min/max bounds and step control. */
export function useCounter(
  initialValue = 0,
  options: UseCounterOptions = {},
): UseCounterReturn {
  const { min, max, step = 1 } = options;
  const [count, setCount] = useState(() => clamp(initialValue, min, max));

  const set = useCallback(
    (value: number | ((prev: number) => number)) => {
      setCount((prev) => {
        const next = typeof value === 'function' ? value(prev) : value;
        return clamp(next, min, max);
      });
    },
    [min, max],
  );

  const inc = useCallback(
    (delta = step) => set((c) => c + delta),
    [set, step],
  );

  const dec = useCallback(
    (delta = step) => set((c) => c - delta),
    [set, step],
  );

  const reset = useCallback(() => {
    setCount(clamp(initialValue, min, max));
  }, [initialValue, min, max]);

  return [count, { inc, dec, set, reset }];
}

Copy-paste example

useCounter.example.tsx
'use client';

import { useCounter } from '@/hooks';

export function Qty() {
  const [count, { inc, dec, reset, set }] = useCounter(1, {
    min: 1,
    max: 99,
    step: 1,
  });

  return (
    <div>
      <button onClick={() => dec()}>-</button>
      <span>{count}</span>
      <button onClick={() => inc()}>+</button>
      <button onClick={() => set(10)}>Set 10</button>
      <button onClick={reset}>Reset</button>
    </div>
  );
}

Production checklist

  • Called only from Client Components or other custom hooks
  • Type parameters filled in (e.g. useFetch<User[]>)
  • Tip: Keep state setters stable; prefer action helpers over manual setState spreads.
  • Source of truth: open hooks/state/useCounter.ts for implementation details