@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 ecosystem — a collection of production-ready React hooks designed for modern applications.

$3

- 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


$3
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
$3
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`

`$3`

`tsx import { useCounter } from "@usefy/use-counter";

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

return (


      {count}


  );
}

$3

`tsx import { useCounter } from "@usefy/use-counter";

function QuantitySelector() { const { count, increment, decrement } = useCounter(1);

return (


              onClick={decrement}
        disabled={count <= 1}
        aria-label="Decrease quantity"
      >
        −
      
      {count}


  );
}

$3

`tsx import { useCounter } from "@usefy/use-counter";

function Pagination({ totalPages }: { totalPages: number }) { const { count: currentPage, increment: nextPage, decrement: prevPage, reset, } = useCounter(1);

return (


      
      
        Page {currentPage} of {totalPages}


  );
}

$3

`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}


  );
}

$3

`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.

$3

📊 View Detailed Coverage Report (GitHub Pages)

$3

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

$3

- Vitest — Fast, modern test runner
- @testing-library/react — React testing utilities
- jsdom — DOM environment for Node.js

---

License

MIT © mirunamu

This package is part of the usefy monorepo.

---

_{Built with care by the usefy team}

@usefy/use-counter

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

Installation •
Quick Start •
API Reference •
Examples •
License

📚 View Storybook Demo

---

Overview

Part of the @usefy ecosystem — a collection of production-ready React hooks designed for modern applications.

$3

---

Installation

``bash

`npm`


npm install @usefy/use-counter
yarn

yarn add @usefy/use-counter
pnpm

pnpm add @usefy/use-counter


$3
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
$3
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

---

`Examples`

`$3`

`tsx import { useCounter } from "@usefy/use-counter";

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

return (


      {count}


  );
}

$3

`tsx import { useCounter } from "@usefy/use-counter";

function QuantitySelector() { const { count, increment, decrement } = useCounter(1);

return (


              onClick={decrement}
        disabled={count <= 1}
        aria-label="Decrease quantity"
      >
        −
      
      {count}


  );
}

$3

`tsx import { useCounter } from "@usefy/use-counter";

function Pagination({ totalPages }: { totalPages: number }) { const { count: currentPage, increment: nextPage, decrement: prevPage, reset, } = useCounter(1);

return (


      
      
        Page {currentPage} of {totalPages}


  );
}

$3

`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}


  );
}

$3

`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`

`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.

$3

📊 View Detailed Coverage Report (GitHub Pages)

$3

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

$3

- Vitest — Fast, modern test runner
- @testing-library/react — React testing utilities
- jsdom — DOM environment for Node.js

---

License

MIT © mirunamu

This package is part of the usefy monorepo.

---

_{Built with care by the usefy team}