useMap
Manage key-value Map state with type-safe operations and immutable updates. Perfect for React applications requiring complex state management with Next.js integration and TypeScript support.
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.jsonFeatures
- Type-safe Map operations with generic key and value types for TypeScript safety
- Immutable state updates ensuring React re-renders trigger correctly on changes
- Comprehensive actions including set, setAll, remove, and reset operations
- Performance optimized using useCallback to prevent unnecessary re-renders
- Flexible initialization supporting both Map instances and key-value arrays
- shadcn/ui integration compatible with form controls and data display components
Examples
Complex Object Management
Advanced task manager demonstrating Map with complex object values and type safety.
Use Cases
This free open source React component works well for:
- Caching systems - Store computed values with unique keys using Next.js and TypeScript
- Entity management - Handle collections of objects by ID with type-safe operations
- Form field tracking - Dynamic form state management with Tailwind CSS styling
- Lookup tables - Fast key-based data access in React applications
API Reference
useMap
| 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 | Omit<Map<K, V>, 'set' | 'clear' | 'delete'> | Read-only Map instance with get, has, size, etc. |
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 |
Usage Patterns
Basic Usage
import { useMap } from '@repo/use-map';
function MyComponent() {
const [map, { set, remove }] = useMap([['initial', 'value']]);
return (
<div>
<button onClick={() => set('key', 'value')}>Add Item</button>
<button onClick={() => remove('key')}>Remove Item</button>
</div>
);
}With TypeScript
type User = { name: string; age: number };
const [users, { set }] = useMap<string, User>();
set('user1', { name: 'John', age: 30 });Implementation Notes
- Map updates create new instances ensuring immutability and proper React updates
- Actions are memoized with useCallback preventing unnecessary child re-renders
- Supports all native Map methods for reading (get, has, size, keys, values, entries)
- Write operations (set, clear, delete) are handled through actions for consistency
- Compatible with React DevTools for state inspection and debugging
- Works with React Concurrent features and Strict Mode