# How to Use the npm uuid Package in React Applications: A Complete Guide to uuid react
> Learn how to use the uuid npm package in React applications to generate unique IDs. Our guide explains uuid react usage with useMemo and state initializers for stable identifiers and preventing hydration mismatches.
- Repository: [Meta/react](https://github.com/facebook/react)
- Tags: how-to-guide
- Published: 2026-02-16
---
**TLDR:** Install the `uuid` package via npm, import the `v4` function, and generate unique identifiers inside `useMemo` or a state initializer to ensure stable IDs that persist across React renders without causing hydration mismatches.
The facebook/react repository provides the `useId` hook for DOM-specific identifiers, but when you need globally unique, opaque identifiers for data entities or component keys, integrating the **uuid react** pattern with the `uuid` library offers the most robust solution. This approach ensures that every identifier remains stable throughout the component lifecycle while avoiding the performance costs of regenerating IDs on every render.
## Why Choose uuid in React Instead of useId
React 18 introduced the `useId` hook, implemented in [`packages/react/src/ReactHooks.js`](https://github.com/facebook/react/blob/main/packages/react/src/ReactHooks.js), which generates short, deterministic identifiers specifically designed for DOM accessibility attributes and label associations. However, `useId` is not designed for **uuid react** use cases requiring global uniqueness across distributed systems.
When you need 128-bit random identifiers for database primary keys, client-side session tracking, or API request correlation, the `uuid` package provides RFC4122-compliant v4 UUIDs. These offer collision resistance across different React trees, browser sessions, and server instances—functionality that React's internal `useId` implementation in [`packages/react/src/ReactFiberHooks.js`](https://github.com/facebook/react/blob/main/packages/react/src/ReactFiberHooks.js) does not provide.
## Installing and Importing the uuid Package
To implement the **uuid react** pattern, first add the package to your project:
```bash
npm install uuid
```
For TypeScript projects, install the corresponding type definitions:
```bash
npm install --save-dev @types/uuid
```
Import the v4 generator—the standard choice for random UUIDs—into your React components:
```javascript
import { v4 as uuidv4 } from 'uuid';
```
## Generating Stable UUIDs in React Components
The critical challenge when implementing **uuid react** solutions is ensuring the identifier is generated exactly once per component instance. React components may render multiple times due to state updates, prop changes, or Strict Mode double-invocation. Generating a new UUID during every render would break key stability and cause hydration mismatches in server-side rendering environments.
### Using useMemo for Render-Safe Identifiers
For identifiers used only during rendering—such as DOM `id` attributes or temporary component keys—wrap the UUID generation in `useMemo` with an empty dependency array:
```tsx
import React, { useMemo } from 'react';
import { v4 as uuidv4 } from 'uuid';
export default function ProfileCard({ name }: { name: string }) {
// Generate a UUID only once – stable across renders
const elementId = useMemo(() => uuidv4(), []);
return (
{name}
);
}
```
This pattern ensures that `elementId` remains constant throughout the component's lifecycle, preventing unnecessary DOM updates or accessibility tree recalculations.
### Using useState Initializer for Persistent IDs
When the UUID needs to be part of the component's state—perhaps to send as a request identifier or to track a specific instance—use the state initializer pattern. This guarantees the UUID is generated only during the initial render:
```tsx
import React, { useState } from 'react';
import { v4 as uuidv4 } from 'uuid';
type Todo = { id: string; text: string };
export default function TodoList() {
const [todos, setTodos] = useState([]);
const addTodo = (text: string) => {
// Generate new UUID for each todo item at creation time
setTodos([...todos, { id: uuidv4(), text }]);
};
return (
<>
{todos.map(todo => (
{todo.text}
))}
);
}
```
In this example, `uuidv4()` is called during the event handler (`addTodo`), not during the render phase, which is safe because it updates state rather than being used directly in the render output calculation.
### Creating a Custom useUuid Hook
For applications that frequently require UUID generation, encapsulate the logic in a custom hook. This promotes consistency and makes it easy to switch implementations later if needed:
```tsx
import { useMemo } from 'react';
import { v4 as uuidv4 } from 'uuid';
export function useUuid(): string {
return useMemo(() => uuidv4(), []);
}
/* Usage in a component */
import React from 'react';
import { useUuid } from './useUuid';
export default function Avatar({ src }: { src: string }) {
const id = useUuid(); // unique, stable across renders
return ;
}
```
## Server-Side Rendering Considerations
When implementing **uuid react** patterns in server-side rendering (SSR) environments, you must account for hydration mismatches. If the server generates a UUID and the client generates a different one during hydration, React will detect a mismatch and potentially remount the component.
For DOM-specific identifiers that must match between server and client, prefer React's built-in `useId` hook, which is implemented in [`packages/react/src/ReactHooks.js`](https://github.com/facebook/react/blob/main/packages/react/src/ReactHooks.js) and designed specifically for SSR compatibility. The `useId` hook generates short, deterministic identifiers that are consistent across the server-client boundary, as verified by the test suite in [`packages/react-dom/src/__tests__/ReactDOMUseId-test.js`](https://github.com/facebook/react/blob/main/packages/react-dom/src/__tests__/ReactDOMUseId-test.js).
Reserve the `uuid` package for data that does not need to be identical between server and client, such as:
- Database primary keys generated after form submission
- Client-side tracking IDs
- Temporary keys for items created purely on the client
## React Internals: How useId Differs from uuid
Understanding React's internal implementation helps clarify when to use the built-in hook versus the **uuid react** approach. The `useId` hook, exposed from [`packages/react/src/ReactHooks.js`](https://github.com/facebook/react/blob/main/packages/react/src/ReactHooks.js) and wired through the reconciler in [`packages/react/src/ReactFiberHooks.js`](https://github.com/facebook/react/blob/main/packages/react/src/ReactFiberHooks.js), utilizes a tree-based identifier system that produces short, stable strings.
In contrast, the `uuid` library generates 128-bit random values formatted as strings like `550e8400-e29b-41d4-a716-446655440000`. While `useId` is optimized for React's reconciliation and SSR hydration, it is not suitable for use as database keys or API identifiers because it is not globally unique across different React trees or applications.
## Summary
- **Install** the `uuid` package via npm to add RFC4122-compliant unique identifier generation to your React application.
- **Import** `v4` as `uuidv4` for random UUID generation, the standard choice for **uuid react** implementations.
- **Stabilize** the generated value using `useMemo` with an empty dependency array or a state initializer to prevent regeneration on every render.
- **Differentiate** between React's built-in `useId` (for DOM accessibility, SSR-safe, short IDs) and `uuid` (for database keys, API correlation, global uniqueness).
- **Avoid** generating UUIDs directly in the render body without memoization to prevent hydration mismatches in SSR environments and unnecessary reconciliation overhead.
## Frequently Asked Questions
### How do I prevent my UUID from changing on every render in React?
Wrap the `uuidv4()` call in `useMemo` with an empty dependency array or use the state initializer pattern with `useState`. Both approaches ensure the identifier is generated only during the initial render and remains stable through subsequent updates. Directly calling `uuidv4()` in the component body without memoization creates a new UUID on every render, breaking key stability and causing performance issues.
### Should I use uuid or React's built-in useId hook?
Use **React's `useId`** when you need short, deterministic identifiers for DOM elements, such as associating labels with inputs or linking aria attributes. The `useId` hook is optimized for server-side rendering and hydration consistency. Use **`uuid`** when you need globally unique identifiers for data entities, such as database primary keys, API request IDs, or client-side tracking tokens that must remain unique across different sessions and users.
### Is the uuid package safe to use with React Server Components?
Yes, the `uuid` package works in React Server Components, but you must handle it carefully to avoid hydration mismatches. If you generate a UUID in a Server Component and pass it to a Client Component, the value will be serialized and consistent. However, if both server and client generate UUIDs independently for the same logical entity, you will encounter hydration errors. For Server Components, generate UUIDs only when creating new data entities, or use React's `useId` for DOM-specific identifiers that must match between server and client.
### How do I generate UUIDs for list items in React?
Generate the UUID at the point of data creation, not during the render of the list. When adding a new item to your state array, call `uuidv4()` to assign the `id` property before calling `setState` or `dispatch`. This ensures the identifier is stable and associated with the data entity itself, not the React component's render cycle. Avoid generating UUIDs inside the `map` function during render, as this would create new keys on every render, breaking React's reconciliation and causing unnecessary DOM updates.