@usefy/use-counter

A lightweight, type-safe React hook for counter state management

Installation • Quick Start • API Reference • Examples • License

--- ## Overview `@usefy/use-counter` is a simple yet powerful React hook for managing counter state. It provides a clean, intuitive API with stable function references, making it ideal for building increment/decrement UIs, pagination controls, quantity selectors, and more. **Part of the [@usefy](https://www.npmjs.com/org/usefy) ecosystem** — a collection of production-ready React hooks designed for modern applications. ### Why use-counter? - **Zero Dependencies** — Pure React implementation with no external dependencies - **TypeScript First** — Full type safety with comprehensive type definitions - **Stable References** — Functions are memoized with `useCallback` for optimal performance - **SSR Compatible** — Works seamlessly with Next.js, Remix, and other SSR frameworks - **Lightweight** — Minimal bundle footprint (~200B minified + gzipped) - **Well Tested** — Comprehensive test coverage with Vitest --- ## Installation ```bash # npm npm install @usefy/use-counter # yarn yarn add @usefy/use-counter # pnpm pnpm add @usefy/use-counter ``` ### Peer Dependencies This package requires React 18 or 19: ```json { "peerDependencies": { "react": "^18.0.0 || ^19.0.0" } } ``` --- ## Quick Start ```tsx import { useCounter } from "@usefy/use-counter"; function Counter() { const { count, increment, decrement, reset } = useCounter(0); return (

Count: {count}

); } ``` --- ## API Reference ### `useCounter(initialValue?)` A hook that manages counter state with increment, decrement, and reset capabilities. #### Parameters | Parameter | Type | Default | Description | | -------------- | -------- | ------- | -------------------------------- | | `initialValue` | `number` | `0` | The initial value of the counter | #### Returns | Property | Type | Description | | ----------- | ------------ | --------------------------------------- | | `count` | `number` | The current counter value | | `increment` | `() => void` | Increases the counter by 1 | | `decrement` | `() => void` | Decreases the counter by 1 | | `reset` | `() => void` | Resets the counter to the initial value | --- ## Examples ### Basic Counter ```tsx import { useCounter } from "@usefy/use-counter"; function BasicCounter() { const { count, increment, decrement, reset } = useCounter(); return (

{count}

); } ``` ### Starting with a Custom Value ```tsx import { useCounter } from "@usefy/use-counter"; function QuantitySelector() { const { count, increment, decrement } = useCounter(1); return (

{count}

); } ``` ### Pagination Control ```tsx import { useCounter } from "@usefy/use-counter"; function Pagination({ totalPages }: { totalPages: number }) { const { count: currentPage, increment: nextPage, decrement: prevPage, reset, } = useCounter(1); return ( ); } ``` ### Multiple Independent Counters ```tsx import { useCounter } from "@usefy/use-counter"; function ScoreBoard() { const teamA = useCounter(0); const teamB = useCounter(0); const resetAll = () => { teamA.reset(); teamB.reset(); }; return (

Team A

{teamA.count}

Team B

{teamB.count}

); } ``` ### With Negative Values ```tsx import { useCounter } from "@usefy/use-counter"; function TemperatureAdjuster() { const { count: temperature, increment, decrement, reset } = useCounter(-10); return (

{temperature}°C

); } ``` --- ## TypeScript This hook is written in TypeScript and provides full type inference out of the box. ```tsx import { useCounter } from "@usefy/use-counter"; // Return type is automatically inferred const { count, increment, decrement, reset } = useCounter(0); // count: number // increment: () => void // decrement: () => void // reset: () => void ``` --- ## Performance The hook uses `useCallback` to memoize all returned functions, ensuring stable references across re-renders. This is particularly important when passing these functions as props to child components or using them as dependencies in other hooks. ```tsx const { increment, decrement, reset } = useCounter(0); // These references remain stable across renders useEffect(() => { // Safe to use as dependencies }, [increment, decrement, reset]); ``` --- ## Testing This package maintains comprehensive test coverage to ensure reliability and stability. ### Test Coverage 📊 View Detailed Coverage Report (GitHub Pages) ### Test Categories

Initialization Tests

- Default value initialization (0) - Custom initial value - Negative initial value - Large number support - Explicit zero initialization

Increment Tests

- Increment from zero - Increment from positive values - Increment from negative values - Multiple consecutive increments

Decrement Tests

- Decrement from positive values - Decrement crossing zero boundary - Decrement from negative values - Multiple consecutive decrements

Reset Tests

- Reset after increment operations - Reset after decrement operations - Reset to negative initial value - Reset to zero - Multiple reset operations

Complex Scenario Tests

- Sequential mixed operations - Zero boundary crossing - State stability verification - Alternating increment/decrement - Large number operations - Multiple independent hook instances - Function reference stability across renders

### Testing Stack - **[Vitest](https://vitest.dev/)** — Fast, modern test runner - **[@testing-library/react](https://testing-library.com/react)** — React testing utilities - **[jsdom](https://github.com/jsdom/jsdom)** — DOM environment for Node.js --- ## License MIT © [mirunamu](https://github.com/mirunamu00) This package is part of the [usefy](https://github.com/mirunamu00/usefy) monorepo. ---

_{Built with care by the usefy team}