@vimazing/hooks

A comprehensive collection of production-ready React hooks for common functionality.

Installation

npm install @vimazing/hooks
# or
yarn add @vimazing/hooks
# or
pnpm add @vimazing/hooks

Peer Dependencies

Some hooks require additional peer dependencies:

npm install @tanstack/react-query react-router

• @tanstack/react-query - Required for: useAuth, useGlobal, useDataControl
• react-router - Required for: useGlobal/useQueryState, useDataControl

Available Hooks

State Management

• useGlobal - Global state management using React Query
• usePersistentState - State persisted to localStorage and URL
• useLocalStorageState - State persisted to localStorage
• useQueryStringState - State synced with URL query parameters
• useMounted - Check if component is mounted (SSR-safe)

Authentication & API

• useAuth - Complete authentication flow with signin, signup, and passkeys
• useClient - HTTP client with automatic token management

Data Management

• useDataControl - Complete data table management with pagination, sorting, and search
• useForm - Powerful form state management with auto-sync

UI & Layout

• useIsMobile - Detect mobile breakpoint (768px)
• useFullscreen - Fullscreen API management
• useFocusZones - Keyboard navigation between focus zones
• usePopover - Popover state management
• useDragAndDrop - Drag and drop functionality

Utilities

• useTimer - High-precision RAF-based timer
• useTimeout - Declarative timeout with cleanup
• useDebounce - Debounce callbacks
• useWebsockets - WebSocket connection with auto-reconnect

Input & Interaction

• useDisableMouse - Disable mouse interactions globally
• usePhotoEditor - Canvas-based photo editing
• useImageLoader - Lazy image loading with MutationObserver

Advanced

• usePasskeys - Passkey/WebAuthn support (standalone)

Usage Examples

Global State

import { useGlobal } from '@vimazing/hooks/useGlobal';

function UserProfile() {
  const [user, setUser] = useGlobal('CURRENT_USER', null);
  
  return (
    <div>
      <p>Welcome, {user?.name}</p>
      <button onClick={() => setUser({ name: 'John' })}>
        Update User
      </button>
    </div>
  );
}

Authentication

import { useAuth } from '@vimazing/hooks/useAuth';

function LoginPage() {
  const { signin, isAuthenticated } = useAuth();
  
  if (isAuthenticated) return <Dashboard />;
  
  return (
    <button onClick={() => signin({ 
      email: 'user@example.com', 
      password: 'pass' 
    })}>
      Sign In
    </button>
  );
}

Data Table with Pagination & Search

import { useDataControl } from '@vimazing/hooks/useDataControl';

function DataTable({ rawData }) {
  const {
    data,
    currentPage,
    pageCount,
    changePage,
    searchQuery,
    setSearchQuery,
    sortBy
  } = useDataControl(rawData);
  
  return (
    <div>
      <input 
        value={searchQuery} 
        onChange={e => setSearchQuery(e.target.value)}
        placeholder="Search..."
      />
      <table>
        <thead>
          <tr>
            <th onClick={() => sortBy('name')}>Name</th>
            <th onClick={() => sortBy('age')}>Age</th>
          </tr>
        </thead>
        <tbody>
          {data?.map(row => (
            <tr key={row.id}>
              <td>{row.name}</td>
              <td>{row.age}</td>
            </tr>
          ))}
        </tbody>
      </table>
      <button onClick={() => changePage(currentPage - 1)}>Prev</button>
      <span>Page {currentPage} of {pageCount}</span>
      <button onClick={() => changePage(currentPage + 1)}>Next</button>
    </div>
  );
}

Timer

import { useTimer } from '@vimazing/hooks/useTimer';

function Stopwatch() {
  const { timeValue, startTimer, stopTimer, resetTimer } = useTimer();
  
  return (
    <div>
      <h1>{(timeValue / 1000).toFixed(2)}s</h1>
      <button onClick={startTimer}>Start</button>
      <button onClick={stopTimer}>Stop</button>
      <button onClick={resetTimer}>Reset</button>
    </div>
  );
}

WebSockets

import { useWebsockets } from '@vimazing/hooks/useWebsockets';

function Chat() {
  const { isOnline, userCount, send } = useWebsockets((msg) => {
    console.log('Message received:', msg);
  });
  
  return (
    <div>
      <span>{isOnline ? '🟢' : '🔴'} {userCount} users online</span>
      <button onClick={() => send({ type: 'ping' })}>
        Ping
      </button>
    </div>
  );
}

Environment Variables

Some hooks require environment variables to be configured:

• VITE_API_URL - Default API endpoint (useClient, useAuth)
• VITE_AUTH_URL - Authentication API endpoint (useAuth)
• VITE_WS_URL - WebSocket endpoint (useWebsockets)
• VITE_FILES_URL - Files API endpoint (useImageLoader)
• VITE_DEFAULT_TABLE_PAGE_SIZE - Default page size for data tables (useDataControl)

TypeScript

All hooks are written in TypeScript and provide full type safety:

import { useGlobal, type UseGlobalReturn } from '@vimazing/hooks/useGlobal';
import { useTimer, type UseTimerReturn } from '@vimazing/hooks/useTimer';

// Return types are automatically exported
const timer: UseTimerReturn = useTimer();

Building

npm run build

This will:

1. Run TypeScript compiler to generate type definitions
2. Use Vite to bundle the library
3. Output to dist/ directory

Publishing

npm publish

The prepublishOnly script will automatically build before publishing.

Features

• 🎯 Type-Safe - Written in TypeScript with full type definitions
• 🪝 Tree-Shakeable - Import only what you need
• ⚡ Zero Dependencies - Core hooks have no dependencies
• 🧪 Production Ready - Battle-tested in real applications
• 📦 Modular - Each hook can be imported individually
• 🔄 React 18/19 - Compatible with latest React versions
• 🌐 SSR Safe - Works with server-side rendering

Contributing

Contributions are welcome! This package is primarily for personal use but PRs for bug fixes and improvements are appreciated.

License

MIT

Author

VIMazing