@ndriadev/react-tools

🎯 The Ultimate React Toolkit

115+ Production-Ready Hooks • 9 Smart Components • 25+ Utilities • Full TypeScript

📚 Documentation • 🎮 Live Demos • 🐛 Report Bug • ✨ Request Feature

---

✨ Why React Tools?

🎨 Developer Experience 💎 TypeScript-first with complete type safety 🎯 Intuitive APIs that feel natural 📖 Rich documentation with live examples 🔍 IntelliSense everywhere	⚡ Performance 🌳 Tree-shakeable - import only what you need 📦 Tiny bundles - optimized for production 🚀 Zero dependencies (except React) ⚙️ Optimized re-renders
🛠️ Battle-Tested ✅ Production-ready hooks and components 🧪 Thoroughly tested patterns 🔒 Type-safe implementations 📱 Cross-platform compatible	🎁 Feature-Rich 🎣 115+ hooks across 5 categories 🧩 9 components for common patterns 🔧 25+ utilities for everyday tasks 🌐 Modern Web APIs integrated

---

🚀 Quick Start

Installation

# npm
npm install @ndriadev/react-tools

# pnpm (recommended)
pnpm add @ndriadev/react-tools

# yarn
yarn add @ndriadev/react-tools

Basic Usage

import { useLocalStorageState, useDebounce, useWebSocket } from '@ndriadev/react-tools'

function App() {
  // Persistent state with localStorage sync
  const [theme, setTheme] = useLocalStorageState('theme', 'dark')

  // Debounced search with automatic cleanup
  const [search, setSearch] = useState('')
  const debouncedSearch = useDebounce(search, 500)

  // WebSocket with auto-reconnect and type-safety
  const ws = useWebSocket<MessageType>({
    url: 'wss://api.example.com',
    reconnect: { attempts: 5, exponentialBackoff: true },
    onMessage: (data) => console.log('Received:', data)
  })

  return <div>Your app here</div>
}

Tree-Shakeable Imports

Import only what you need for optimal bundle size:

// ✅ Import entire library (tree-shakeable)
import { useState History, useWebSocket } from '@ndriadev/react-tools'

// ✅ Import by category
import { useStateHistory } from '@ndriadev/react-tools/hooks/state'
import { useWebSocket } from '@ndriadev/react-tools/hooks/api-dom'

// ✅ Import components separately
import { SwitchCase, ErrorBoundary } from '@ndriadev/react-tools/components'

// ✅ Import utilities
import { isDeepEqual, mergeObjects } from '@ndriadev/react-tools/utils'

---

📦 What's Inside?

🎣 Hooks (115+)

🗂️ State Management (17 hooks)

Advanced state management with history, validation, and persistence:

Hook	Description
useStateHistory	useState with undo/redo and time-travel
useReducerHistory	useReducer with history tracking
useLocalStorageState	Sync state with localStorage
useSessionStorageState	Sync state with sessionStorage
useProxyState	Deep reactive state with Proxy
useStateValidator	State with built-in validation
useDerivedState	Computed state from props
usePrevious	Track previous value
useArray	Array manipulation utilities
useMap	Map state management
useSet	Set state management
createPubSubStore	Global pub/sub state

// Example: Undo/Redo functionality
const [count, setCount, { undo, redo, canUndo, canRedo }] = useStateHistory(0, 10)

<button onClick={() => setCount(c => c + 1)}>Increment</button>
<button onClick={undo} disabled={!canUndo}>Undo</button>
<button onClick={redo} disabled={!canRedo}>Redo</button>

♻️ Lifecycle (12 hooks)

Enhanced lifecycle hooks with custom comparison and abort control:

• useEffectOnce - Run effect only once
• useEffectCompare - Custom dependency comparison
• useEffectDeepCompare - Deep equality check
• useEffectAbortable - Built-in AbortController
• useLayoutEffect* variants
• useIsMounted - Check mount status
• useLogger - Debug lifecycle changes

// Example: Deep comparison for objects
useEffectDeepCompare(() => {
  fetchData(filters) // Only runs when filters deeply change
}, [filters])

⚡ Performance (8 hooks)

Optimize your components with smart memoization:

• useMemoizedFn - Stable function references
• useMemoCompare / useCallbackCompare - Custom comparison
• useLazyRef - Lazy initialization
• useMergedRef - Merge multiple refs
• useId - Unique IDs (React 18 polyfill)

// Example: Stable callback without dependencies
const handleClick = useMemoizedFn((id) => {
  // Always has access to latest state
  // But reference never changes
  console.log('Clicked:', id, latestState)
})

👆 Events (25 hooks)

Handle user interactions and DOM events efficiently:

Mouse & Touch:

• useClickOutside - Detect clicks outside element
• useHover - Hover state
• useDoubleClick - Distinguish single/double click
• useLongPress - Long press detection
• useSwipe - Swipe gestures
• usePinchZoom - Pinch-to-zoom

Observers:

• useIntersectionObserver - Visibility detection
• useResizeObserver - Element size changes
• useMutationObserver - DOM mutations

Keyboard & Actions:

• useHotKeys - Keyboard shortcuts
• usePerformAction - Action delegation pattern
• useEventListener - Generic event handling

Network & System:

• useIsOnline - Online/offline status
• useNetwork - Network information
• useBeforeUnload - Prevent page close

// Example: Click outside to close
const ref = useClickOutside(() => setIsOpen(false))
<div ref={ref}>{isOpen && <Dropdown />}</div>

🌐 Web APIs (50+ hooks)

Modern browser APIs made easy:

Media:

• useAudio / useVideo - Media element control
• useMediaDevices - Camera/microphone access
• useDisplayMedia - Screen sharing
• usePIP - Picture-in-Picture
• useSpeechRecognition / useSpeechSynthesis

Communication:

• useWebSocket - WebSocket with reconnection
• useWebWorker - Multi-threading
• useFetch - Fetch with abort & caching
• useEventSource - Server-Sent Events
• useBroadcastChannel - Cross-tab messaging

Device & Sensors:

• useBattery - Battery status
• useGeolocation - GPS location
• useDeviceOrientation / useDeviceMotion
• useVibrate - Haptic feedback

UI & UX:

• useFullscreen - Fullscreen mode
• useClipboard - Clipboard operations
• useColorScheme - Dark/light mode
• useShare - Web Share API
• useEyeDropper - Color picker

// Example: WebSocket with auto-reconnect
const ws = useWebSocket({
  url: 'wss://api.example.com',
  reconnect: {
    attempts: 5,
    exponentialBackoff: true
  },
  parser: 'json',
  onMessage: (data) => updateUI(data)
})

ws.sendJSON({ type: 'ping' })

🧩 Components (9)

Conditional Rendering:

// Show/Hide with fallback
<Show when={isLoggedIn} fallback={<Login />}>
  <Dashboard />
</Show>

// Switch-case logic
<SwitchCase.Switch>
  <SwitchCase.Case when={status === 'loading'}>
    <Spinner />
  </SwitchCase.Case>
  <SwitchCase.Case when={status === 'error'}>
    <Error />
  </SwitchCase.Case>
</SwitchCase.Switch>

List Rendering:

// Optimized list rendering
<For each={items} fallback={<EmptyState />}>
  {(item, index) => <ItemCard key={item.id} {...item} />}
</For>

Error Handling:

// Error boundary with reset
<ErrorBoundary
  fallback={(error, reset) => (
    <ErrorDisplay error={error} onReset={reset} />
  )}
  onError={(error) => logToService(error)}
>
  <App />
</ErrorBoundary>

Lazy Loading:

// Advanced lazy loading with retry
<LazyComponent
  loader={() => import('./HeavyComponent')}
  loading={<Skeleton />}
  error={(retry) => <ErrorWithRetry onRetry={retry} />}
/>

🔧 Utilities (25+)

Type Guards:

• isDeepEqual / isShallowEqual - Equality checks
• isMouseEvent / isTouchEvent - Event type guards
• isAsync - Async function detection
• isClient - SSR detection

Object & Array:

• mergeObjects - Deep merge
• getObjectFromDottedString - Path access ("user.profile.name")
• uniqueElementsArray - Remove duplicates
• alphanumericCompare - Natural sorting

String:

• changeStringCase - Convert between cases
• detectBrowser - Browser detection

DOM:

• clickElementOnKeydownEvent - Accessibility helper
• hotKeyHandler - Keyboard shortcuts
• getBase64 - File conversion

Patterns:

• PublishSubscribePattern - Pub/Sub implementation
• EventsPattern - Event emitter
• lazy - Lazy function execution

---

📊 Browser Support

Browser	Version
Chrome	≥ 90
Firefox	≥ 88
Safari	≥ 14
Edge	≥ 90

React Compatibility: React ≥ 16.8.0 (Hooks support required)

---

🎯 Use Cases

📱 Modern Web Apps Perfect for SPAs with complex state management and real-time features

🏢 Enterprise Applications Battle-tested patterns for large-scale applications with strict requirements

🚀 Rapid Prototyping Skip boilerplate and focus on features with ready-to-use hooks

---

📝 Changelog

See CHANGELOG.md for release history and breaking changes.

📄 License

MIT © nDriaDev

---

📞 Support

• Documentation: futurable.ndria.dev
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: info@ndria.dev

---

If you find Futurable useful, please consider giving it a ⭐ on GitHub!