UUID in React and Next.js — Patterns and Pitfalls

UUID generation in React and Next.js is straightforward until it is not. The two main pitfalls are hydration mismatches (generating different values on server and client) and unstable keys (generating a new UUID on every render). This article covers both problems, the correct patterns for each framework, and the App Router server action approach.

The hydration mismatch problem

In a Next.js application with server-side rendering, React renders the component tree on the server and sends HTML to the browser. When the JavaScript loads, React renders again on the client and compares the result to the server HTML. If they differ, React throws a hydration error.

UUID generation breaks this because crypto.randomUUID() produces a different value each time:

// ❌ Hydration error — server and client produce different UUIDs
function Form() {
  const formId = crypto.randomUUID(); // different on every render
  return <form id={formId}>...</form>;
}

// ❌ Also wrong — useState initialiser runs on both server and client
function Form() {
  const [id] = useState(() => crypto.randomUUID()); // mismatches on hydration
  return <form id={id}>...</form>;
}

Fix 1: generate server-side only

In Next.js App Router, generate the UUID in a Server Component where there is no hydration:

// app/form/page.tsx — Server Component (no 'use client')
import { v7 as uuidv7 } from 'uuid';

export default function FormPage() {
  const formId = uuidv7(); // runs once on the server, never on client
  return <Form id={formId} />;
}

The formId is stable because it is generated once during server rendering and sent as a prop.

Fix 2: generate after mount with useEffect

For Client Components that need a UUID for purely client-side concerns:

'use client';
import { useState, useEffect } from 'react';
import { v7 as uuidv7 } from 'uuid';

function Form() {
  const [formId, setFormId] = useState<string>('');

  useEffect(() => {
    setFormId(uuidv7()); // runs only on client, after hydration
  }, []);

  if (!formId) return null; // or a skeleton
  return <form id={formId}>...</form>;
}

useEffect runs after hydration, so the server renders with an empty formId and the client populates it after mount. Avoid this pattern unless you genuinely need a client-generated ID — the flash of empty state is a UX cost.

Fix 3: suppress hydration warning (last resort)

For non-critical attributes where the mismatch is harmless:

<div id={crypto.randomUUID()} suppressHydrationWarning>

Only use this when the differing value does not affect functionality. Never suppress warnings for IDs used in form labels, ARIA attributes, or JavaScript logic.

UUID as React keys

React keys must be stable across renders. Using crypto.randomUUID() as a key directly is a common mistake:

// ❌ Wrong — generates new UUID on every render, causes remount
{items.map((item) => (
  <Item key={crypto.randomUUID()} data={item} />
))}

// ✓ Correct — UUID assigned when item is created, stable thereafter
{items.map((item) => (
  <Item key={item.id} data={item} />  // item.id is a UUID from the server or state
))}

If items come from a local state array and have no server-assigned ID, generate the UUID when the item is added to state — not during render:

'use client';
import { useState } from 'react';
import { v7 as uuidv7 } from 'uuid';

interface TodoItem {
  id: string;
  text: string;
}

function TodoList() {
  const [todos, setTodos] = useState<TodoItem[]>([]);

  function addTodo(text: string) {
    setTodos((prev) => [...prev, { id: uuidv7(), text }]); // UUID assigned once
  }

  return (
    <ul>
      {todos.map((todo) => (
        <li key={todo.id}>{todo.text}</li>  // stable key
      ))}
    </ul>
  );
}

Next.js App Router: Server Actions

Server Actions are the cleanest pattern for UUID generation in App Router — the UUID is created on the server, never touches the client:

// app/actions.ts
'use server';
import { v7 as uuidv7 } from 'uuid';
import { db } from '@/lib/db';

export async function createOrder(formData: FormData) {
  const orderId = uuidv7(); // server-only, no hydration concern

  await db.order.create({
    data: {
      id: orderId,
      userId: formData.get('userId') as string,
      total: Number(formData.get('total')),
    },
  });

  return { orderId };
}

// app/checkout/page.tsx
'use client';
import { createOrder } from '../actions';

function CheckoutForm() {
  async function handleSubmit(formData: FormData) {
    const { orderId } = await createOrder(formData);
    // orderId is a UUID v7 generated on the server
    window.location.href = `/orders/${orderId}`;
  }

  return <form action={handleSubmit}>...</form>;
}

useId() for accessibility — not UUIDs

React 18 added useId() for generating stable IDs for accessibility attributes (form labels, ARIA). It produces hydration-safe IDs but they are not UUIDs — they look like :r0:, :r1:, etc.

Use useId() when you need a stable HTML element ID for htmlFor/aria-labelledby. Use UUID v7 when you need a globally unique identifier for a data record.

// ✓ useId() for form accessibility
function EmailInput() {
  const id = useId();
  return (
    <>
      <label htmlFor={id}>Email</label>
      <input id={id} type="email" />
    </>
  );
}

// ✓ UUID v7 for record identity
async function createUser(email: string) {
  const userId = uuidv7();
  await db.user.create({ data: { id: userId, email } });
  return userId;
}

Summary

Further reading

• UUID in JavaScript — crypto.randomUUID(), uuid npm package, Prisma and Drizzle patterns
• TypeScript UUID Types — branded types for compile-time ID safety
• UUID v7 ORM Support in 2026 — Prisma and Drizzle UUID v7 configuration