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 · useCounterEditor
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.tsfor implementation details