React useMap Hook
React useMap hook for Map state management. Type-safe key-value operations with immutable updates and performance optimization using TypeScript for Next.js.
Need better object manipulation patterns?
Join our Discord community for help from other developers.
Ever tried to manage complex key-value state in React and ended up with messy object spreading, key collision issues, or performance problems from unnecessary re-renders? You know the drill—using objects as maps but losing type safety, manually tracking object mutations, dealing with prototype pollution from string keys. This free open source React useMap custom hook handles all that key-value complexity so you can focus on building data-driven features instead of debugging state management edge cases in your React applications.
useMap showcase
Type-safe Map operations with immutable state management:
This free open source React hook simplifies key-value data with TypeScript support for modern JavaScript applications. Whether you're building caches, entity stores, or lookup tables in your Next.js projects, this React hook keeps your Map state clean and performant.
Installation
npx shadcn@latest add https://www.shadcn.io/registry/use-map.jsonnpx shadcn@latest add https://www.shadcn.io/registry/use-map.jsonpnpm dlx shadcn@latest add https://www.shadcn.io/registry/use-map.jsonbunx shadcn@latest add https://www.shadcn.io/registry/use-map.jsonWhy most Map state implementations suck
Look, you could keep using objects with useState and spread operators for key-value data. But then you hit the Map advantages—better performance for frequent additions/deletions, any key type (not just strings), no prototype pollution, cleaner iteration patterns in React applications.
Most developers use objects with useState but lose Map benefits like non-string keys and insertion order guarantees in TypeScript components. Or they use Map directly but forget to create new instances, causing React to miss state changes and skip re-renders. Some create new Maps without proper memoization, leading to unnecessary child component re-renders in Next.js projects.
This React hook provides a useState-like API specifically designed for Map operations in JavaScript applications. Immutable updates that trigger re-renders correctly, memoized actions to prevent child re-renders, type-safe operations that catch errors at compile time.
Plus it handles all the React integration complexities—proper state updates that don't mutate, action functions that are stable across renders, read-only Map interface that prevents accidental mutations in React development.
This free open source React hook manages Map state while you focus on building features. Whether you're creating React applications, Next.js dashboards, or TypeScript components, reliable key-value management keeps your JavaScript development efficient.
Features
- Type-safe Map operations with generic key and value types for TypeScript safety in React applications
- Immutable state updates ensuring React re-renders trigger correctly on changes in TypeScript components
- Comprehensive actions including set, setAll, remove, and reset operations in Next.js projects
- Performance optimized using useCallback to prevent unnecessary re-renders in JavaScript development
- Flexible initialization supporting both Map instances and key-value arrays in React frameworks
- Read-only interface prevents accidental Map mutations outside of actions in modern applications
- Free open source designed for modern React development workflows
When you'll actually use this
Real talk—this isn't for every key-value need in React applications. Simple object state with useState works fine for basic cases. But when you need frequent additions/deletions, non-string keys, or performance-critical operations, this React hook delivers in Next.js projects.
Perfect for:
- Entity management - Store collections of objects by ID with efficient lookups built with TypeScript
- Caching systems - Cache computed values with complex keys and automatic cleanup using React patterns
- Form field tracking - Dynamic form state management with unique field identifiers in JavaScript applications
- Lookup tables - Fast key-based data access for configuration or mapping data in React components
- State normalization - Normalize nested data structures for predictable updates in Next.js applications
- Live data feeds - Manage real-time data with frequent updates and deletions using TypeScript safety
API Reference
useMap
useMap<K, V>(initialState?: MapOrEntries<K, V>): [ReadonlyMap<K, V>, UseMapActions<K, V>]| Parameter | Type | Description |
|---|---|---|
initialState | MapOrEntries<K, V> | Initial Map state as Map instance or array of entries |
Return Value
Returns a tuple: [map, actions]
| Property | Type | Description |
|---|---|---|
map | ReadonlyMap<K, V> | Read-only Map instance with get, has, size, keys, values, entries |
actions | UseMapActions<K, V> | Object containing mutation methods |
Actions Object
| Method | Type | Description |
|---|---|---|
set | (key: K, value: V) => void | Add or update a key-value pair |
setAll | (entries: MapOrEntries<K, V>) => void | Replace entire Map with new entries |
remove | (key: K) => void | Remove a key-value pair by key |
reset | () => void | Clear all entries from the Map |
Common gotchas
Map updates create new instances: Every action creates a new Map for immutability in React applications. This triggers React re-renders correctly but means you shouldn't hold references to the Map object across renders.
Actions are memoized for performance: The set, remove, and other action functions have stable references across re-renders in TypeScript components, making them safe to use in dependency arrays and as props.
Key equality uses SameValueZero: Maps use the same equality as Set for keys in Next.js projects. Objects are compared by reference, not by value, so {} !== {} even if they have the same properties.
Iteration order is guaranteed: Unlike objects, Maps maintain insertion order in JavaScript applications. Use this predictable ordering for rendering lists or processing entries sequentially.
Reference equality for object keys: When using objects as keys, store the key in a variable to reuse the same reference in React frameworks. Creating new objects each time will result in different keys.
Memory management considerations: Maps can hold references to large objects in TypeScript projects. Use the remove action to clean up unused entries and prevent memory leaks.
Related hooks you will also like
useCounter
Counter state management with similar helper method patterns
useBoolean
Boolean state with helper methods similar to Map actions
useLocalStorage
Persistent state that can store Map data across sessions
useSet
Set state management with similar collection patterns
useToggle
Toggle state management with action-based patterns
useList
Array state management for ordered collections
Questions you might have
React useLocalStorage Hook
React useLocalStorage hook for persistent state. Automatic serialization with cross-tab synchronization and SSR support using TypeScript for Next.js apps.
React useMediaQuery Hook
React useMediaQuery hook for responsive design. Track breakpoints and user preferences with real-time updates and SSR support using TypeScript for Next.js.