modern-react-hooks

Zero-dependency, TypeScript-first React hooks for modern development

Why modern-react-hooks?

• 🚀 2-3x smaller than alternatives (15kb vs 45kb gzipped)
• 💪 100% TypeScript with perfect inference
• 🔒 Zero dependencies for maximum security
• 🌳 Tree-shakeable - import only what you need
• ⚡ React 18+ optimized with Concurrent features
• 🧪 100% test coverage for reliability
• 📦 ESM + CJS dual build support
• 🎯 Modern JavaScript (ES2020+)

Installation

npm install modern-react-hooks

yarn add modern-react-hooks

pnpm add modern-react-hooks

Quick Start

import { useLocalStorage, useDebounce } from 'modern-react-hooks'

function App() {
  const [theme, setTheme] = useLocalStorage('theme', 'light')
  const [searchTerm, setSearchTerm] = useState('')
  const debouncedSearchTerm = useDebounce(searchTerm, 300)
  
  return (
    <div>
      <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
        Toggle theme: {theme}
      </button>
      <input
        value={searchTerm}
        onChange={(e) => setSearchTerm(e.target.value)}
        placeholder="Search..."
      />
      <p>Debounced: {debouncedSearchTerm}</p>
    </div>
  )
}

Available Hooks

State Management

useLocalStorage<T>(key, initialValue, options?)

Persistent state with localStorage synchronization.

const [user, setUser] = useLocalStorage('user', { name: 'Guest' })
const [count, setCount, removeCount] = useLocalStorage('count', 0)

// With options
const [settings, setSettings] = useLocalStorage('settings', {}, {
  syncAcrossTabs: true,
  onError: (error) => console.warn(error),
  serializer: customSerializer
})

Parameters:

• key: string - localStorage key
• initialValue: T - Default value when key doesn't exist
• options?: StorageOptions<T> - Configuration options

Returns: [value, setValue, removeValue]

useToggle<T>(initialValue, toggleFunction?)

Boolean toggle state with custom toggle logic.

const [isOpen, toggle] = useToggle(false)
const [status, toggleStatus] = useToggle('active', (current) => 
  current === 'active' ? 'inactive' : 'active'
)

toggle() // Toggles between true/false
toggle(true) // Sets to specific value

Parameters:

• initialValue: T - Initial state value
• toggleFunction?: (value: T) => T - Custom toggle logic

Returns: [value, toggle]

Performance Optimization

useDebounce<T>(value, delay)

Debounce rapidly changing values.

const [searchQuery, setSearchQuery] = useState('')
const debouncedQuery = useDebounce(searchQuery, 500)

useEffect(() => {
  if (debouncedQuery) {
    searchAPI(debouncedQuery)
  }
}, [debouncedQuery])

Parameters:

• value: T - Value to debounce
• delay: number - Delay in milliseconds

Returns: T - Debounced value

DOM & Events

useClickOutside<T>(handler, options?)

Detect clicks outside an element.

const [isOpen, setIsOpen] = useState(false)
const modalRef = useClickOutside<HTMLDivElement>(() => {
  setIsOpen(false)
})

return (
  <div ref={modalRef} className="modal">
    Modal content
  </div>
)

Parameters:

• handler: (event: Event) => void - Callback for outside clicks
• options?: UseClickOutsideOptions - Configuration options

Returns: RefObject<T> - Ref to attach to element

Tree Shaking & Bundle Size

Import only what you need for optimal bundle size:

// Import specific hooks (recommended)
import { useLocalStorage } from 'modern-react-hooks/useLocalStorage'
import { useDebounce } from 'modern-react-hooks/useDebounce'

// Or import from main entry
import { useLocalStorage, useDebounce } from 'modern-react-hooks'

Bundle Size Comparison

| Hook | Gzipped Size | |------|--------------| | useLocalStorage | ~800 bytes | | useDebounce | ~400 bytes | | useClickOutside | ~600 bytes | | useToggle | ~200 bytes | | Total Bundle | ~15kb |

Compare with alternatives:

• react-use: ~45kb gzipped
• rooks: ~35kb gzipped
• ahooks: ~50kb gzipped

TypeScript Support

Perfect TypeScript integration with full type inference:

// Type is automatically inferred as string
const [name, setName] = useLocalStorage('username', 'guest')

// Explicit typing for complex objects
interface User {
  id: number
  name: string
  email: string
}

const [user, setUser] = useLocalStorage<User>('user', {
  id: 0,
  name: '',
  email: ''
})

// Custom serializer with proper typing
const dateSerializer = {
  parse: (value: string): Date => new Date(value),
  stringify: (value: Date): string => value.toISOString()
}

const [lastLogin, setLastLogin] = useLocalStorage('lastLogin', new Date(), {
  serializer: dateSerializer
})

Server-Side Rendering (SSR)

All hooks are SSR-safe and work with:

• Next.js
• Gatsby
• Remix
• Any SSR React framework

// Safe to use in SSR environments
function MyComponent() {
  const [theme, setTheme] = useLocalStorage('theme', 'light')
  
  // Initial render will use 'light', then hydrate with actual value
  return <div className={theme}>Content</div>
}

Error Handling

Built-in error handling with optional custom error callbacks:

const [data, setData] = useLocalStorage('data', null, {
  onError: (error) => {
    // Custom error handling
    console.error('Storage error:', error)
    analytics.track('storage_error', { error: error.message })
  }
})

Browser Support

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+

Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Build the library
npm run build

# Run type checking
npm run type-check

# Lint code
npm run lint

Contributing

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

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT © kynuxdev

Roadmap

• [ ] useCounter - Numeric counter with min/max bounds
• [ ] useBoolean - Boolean state utilities
• [ ] useArray - Array state management
• [ ] useCopyToClipboard - Clipboard operations
• [ ] useThrottle - Throttled functions
• [ ] usePrevious - Previous value tracking
• [ ] useSessionStorage - Session storage state
• [ ] Performance optimizations
• [ ] React 19 compatibility
• [ ] Storybook documentation

Made with ❤️ for the React community