@gmana/react-hooks

A comprehensive collection of production-ready React hooks for modern applications. Built with TypeScript and fully tested.

✨ Features

• 🚀 53+ Production-Ready Hooks - Covering state management, UI interactions, network requests, and more
• 📦 TypeScript Support - Full type safety with comprehensive TypeScript definitions
• 🧪 Thoroughly Tested - Complete test coverage with Vitest
• 📱 Mobile-First - Responsive design helpers and mobile-optimized hooks
• 🎯 Tree-Shakable - Import only what you need
• ⚡ Next.js Ready - Full SSR support and hydration safety for Next.js applications
• 🔄 Server-Side Rendering - SSR compatible with Next.js and other frameworks
• 📖 Well Documented - Comprehensive examples and API documentation

📦 Installation

# npm
npm install @gmana/react-hooks

# yarn
yarn add @gmana/react-hooks

# pnpm
pnpm add @gmana/react-hooks

# bun
bun add @gmana/react-hooks

🚀 Quick Start

import React from "react"
import { useBoolean, useCounter, useFetch } from "@gmana/react-hooks"

function App() {
  const { value: isVisible, toggle } = useBoolean(false)
  const { count, increment, decrement } = useCounter(0)
  const { data, error } = useFetch<{ title: string }>("https://api.example.com/data")

  if (error) return <div>Error loading data</div>
  if (!data) return <div>Loading...</div>

  return (
    <div>
      <h1>{data.title}</h1>
      <p>Count: {count}</p>
      <button onClick={increment}>+</button>
      <button onClick={decrement}>-</button>

      <button onClick={toggle}>{isVisible ? "Hide" : "Show"} Content</button>
      {isVisible && <div>Toggle content</div>}
    </div>
  )
}

📚 Available Hooks

🔄 State Management

• useBoolean - Manage boolean state with helper functions
• useCounter - Counter with increment, decrement, and reset
• useToggle - Toggle between values with customizable states
• useToggleState - Advanced toggle state management
• useArray - Array manipulation with push, filter, remove operations
• useMap - Map data structure with CRUD operations
• useStep - Multi-step form/wizard state management

🎨 UI & Layout

• useElementSize - Track element dimensions
• useWindowSize - Monitor window dimensions
• useDimensions - Get container dimensions
• useHover - Detect hover state on elements
• useInView - Check if element is in viewport
• useIntersectionObserver - Advanced intersection observer
• useOnClickOutside - Detect clicks outside element
• useLockedBody - Lock/unlock body scroll
• useSidebar - Sidebar state management

🌐 Network & Data

• useFetch - HTTP requests with caching and error handling
• useNetworkInformation - Network connection details
• useOfflineDetector - Online/offline status detection

💾 Storage & Persistence

• useLocalStorage - Local storage with synchronization
• useReadLocalStorage - Read-only local storage access
• useCookies - Cookie management utilities

📱 Device & Browser APIs

• useMediaQuery - CSS media query matching
• useMobile - Mobile device detection
• useScreen - Screen information access
• useClipboard - Clipboard operations
• useCopyToClipboard - Copy text to clipboard
• useEstimateStorage - Storage quota estimation
• useScript - Dynamic script loading

⏱️ Timing & Effects

• useDebounce - Debounce values and callbacks
• useDebounceA - Alternative debounce implementation
• useDebounceB - Callback-based debouncing
• useTimeout - Declarative setTimeout
• useInterval - Declarative setInterval
• useCountdown - Countdown timer with controls

🔧 Utilities

• useIsClient - Client-side rendering detection
• useIsFirstRender - First render detection
• useIsMounted - Component mount status
• useSSR - Server-side rendering utilities
• useEffectOnce - Run effect only once
• useUpdateEffect - Skip effect on first render
• useIsomorphicLayoutEffect - SSR-safe layout effect
• useEventListener - Event listener management
• useImageOnLoad - Image loading state management
• useUnloadWarning - Page unload warning

🎨 Theme & Appearance

• useDarkMode - Simple dark mode toggle
• useTernaryDarkMode - Advanced theme management (light/dark/system)

⚡ Performance & Optimization

• useDebounce - Debounce values for performance optimization
• useDebounceCallback - Debounce function calls
• useThrottle - Throttle function execution
• usePrevious - Access previous values
• useAsyncEffect - Handle async operations in effects safely

🔧 Next.js & SSR

• useHydrated - Detect hydration state for Next.js
• useIsClient - Client-side rendering detection
• useSSR - Server-side rendering utilities
• useIsomorphicLayoutEffect - SSR-safe layout effects

💡 Usage Examples

State Management

import { useBoolean, useCounter, useArray } from "@gmana/react-hooks"

function StateExample() {
  // Boolean state with helpers
  const { value: isOpen, setTrue: open, setFalse: close, toggle } = useBoolean(false)

  // Counter with operations
  const { count, increment, decrement, reset } = useCounter(0)

  // Array management
  const { array, push, remove, filter, clear } = useArray([1, 2, 3])

  return (
    <div>
      <button onClick={toggle}>{isOpen ? "Close" : "Open"}</button>
      <button onClick={increment}>Count: {count}</button>
      <div>Array: {array.join(", ")}</div>
      <button onClick={() => push(Math.random())}>Add Random</button>
    </div>
  )
}

UI Interactions

import { useHover, useOnClickOutside, useElementSize } from "@gmana/react-hooks"

function UIExample() {
  const [setRef, { width, height }] = useElementSize()
  const hoverRef = useRef(null)
  const isHovered = useHover(hoverRef)

  const dropdownRef = useRef(null)
  const [isDropdownOpen, setIsDropdownOpen] = useState(false)

  useOnClickOutside(dropdownRef, () => setIsDropdownOpen(false))

  return (
    <div ref={setRef}>
      <p>
        Element size: {width}x{height}
      </p>

      <div ref={hoverRef} style={{ background: isHovered ? "blue" : "gray" }}>
        Hover me!
      </div>

      <div ref={dropdownRef}>
        <button onClick={() => setIsDropdownOpen(!isDropdownOpen)}>Toggle Dropdown</button>
        {isDropdownOpen && <div>Dropdown content</div>}
      </div>
    </div>
  )
}

Data Fetching

import { useFetch, useDebounce } from "@gmana/react-hooks"

function DataExample() {
  const [query, setQuery] = useState("")
  const debouncedQuery = useDebounce(query, 500)

  const { data, error } = useFetch(debouncedQuery ? `https://api.example.com/search?q=${debouncedQuery}` : null)

  return (
    <div>
      <input value={query} onChange={(e) => setQuery(e.target.value)} placeholder="Search..." />
      {error && <p>Error: {error.message}</p>}
      {data && <pre>{JSON.stringify(data, null, 2)}</pre>}
    </div>
  )
}

Theme Management

import { useDarkMode, useTernaryDarkMode } from "@gmana/react-hooks"

function ThemeExample() {
  // Simple dark mode
  const { isDarkMode, toggle, enable, disable } = useDarkMode()

  // Advanced theme with system preference
  const { isDarkMode: isAdvancedDark, ternaryDarkMode, setTernaryDarkMode } = useTernaryDarkMode()

  return (
    <div className={isDarkMode ? "dark" : "light"}>
      <button onClick={toggle}>{isDarkMode ? "Light" : "Dark"} Mode</button>

      <select value={ternaryDarkMode} onChange={(e) => setTernaryDarkMode(e.target.value)}>
        <option value="light">Light</option>
        <option value="dark">Dark</option>
        <option value="system">System</option>
      </select>
    </div>
  )
}

Next.js Integration

import { useHydrated, useMediaQuery } from "@gmana/react-hooks"

function NextJSExample() {
  const isHydrated = useHydrated()
  const isMobile = useMediaQuery("(max-width: 768px)")

  // Prevent hydration mismatches
  if (!isHydrated) {
    return <div>Loading...</div>
  }

  return (
    <div>
      <h1>My Next.js App</h1>
      {isMobile ? <MobileLayout /> : <DesktopLayout />}
    </div>
  )
}

🛠️ Development

Prerequisites

• Node.js ≥ 18
• Bun ≥ 1.0.0 (recommended) or npm/yarn

Setup

# Clone the repository
git clone https://github.com/sun-sreng/npm-gmana-react-hooks.git
cd npm-gmana-react-hooks

# Install dependencies
bun install

# Start development mode
bun run dev

Scripts

• bun run dev - Start development mode with watch
• bun run build - Build the library
• bun run test - Run tests
• bun run test:watch - Run tests in watch mode
• bun run lint - Lint code
• bun run format - Format code with Prettier
• bun run check - Run linting and format checks

Testing

We use Vitest for testing with React Testing Library:

# Run all tests
bun run test

# Run tests in watch mode
bun run test:watch

# Run specific test file
bun run test src/lib/use-boolean.test.ts

Building

The library is built using Rolldown for optimal performance:

bun run build

This generates:

• dist/index.js - ES module bundle
• dist/index.d.ts - TypeScript declarations

📋 Requirements

Peer Dependencies

• React ≥ 16.8.0 (hooks support)
• TypeScript ≥ 5.0.0 (for TypeScript projects)

Browser Support

• Modern browsers with ES2022 support
• React Native (most hooks)
• Next.js 13+ with App Router and Pages Router
• Server-Side Rendering environments

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Quick Contribution Guide

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-hook
3. Add your hook with tests and documentation
4. Run tests: bun run test
5. Submit a pull request

Adding a New Hook

1. Create your hook in src/lib/use-your-hook.ts
2. Add comprehensive tests in src/lib/use-your-hook.test.ts
3. Export the hook in src/index.ts
4. Update this README with documentation

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• React team for the amazing hooks API
• All contributors who helped build this library
• The open-source community for inspiration and feedback

📖 Documentation

• 📚 Next.js Integration Guide - Complete guide for using with Next.js
• 🔧 Development Guide - Information for contributors and maintainers

📞 Support

• 🐛 Report Issues
• 💡 Request Features
• 💖 Sponsor

Made with ❤️ by Sun Sreng