How to fix Warning: Prop `key` did not match in React

What this error means

This warning is a React hydration error that occurs during server-side rendering (SSR) when the `key` prop assigned to an element on the server doesn't match the `key` prop React expects during client-side hydration. Hydration is the process where React converts pre-rendered HTML from the server into a fully interactive application by attaching event handlers and reconciling the virtual DOM. React expects the server-rendered HTML and the initial client render to be identical, including all props like `key`. When React detects that a `key` prop differs between server and client, it issues this warning because the mismatch can cause incorrect DOM updates, lost component state, or rendering inconsistencies. The `key` prop is critical for React's reconciliation algorithm—it helps React identify which elements changed, were added, or were removed in lists.

Typical symptoms

• Console warning "Warning: Prop `key` did not match. Server: [value] Client: [different value]" during page load
• Components in lists re-mounting unexpectedly after hydration completes
• Visual flickers or layout shifts when the page becomes interactive
• Component state (like input values or scroll position) being reset after hydration
• Error only appears in production builds with SSR enabled, not in development client-only mode
• Warning appears specifically on pages using Next.js, Gatsby, or other SSR frameworks
• Issue occurs intermittently when using dynamic or time-based key generation

Common causes

1. Using non-deterministic values for keys like Math.random(), Date.now(), or crypto.randomUUID() that generate different values on server and client
2. Generating keys based on browser-only APIs (window, localStorage, sessionStorage) that are undefined during server-side rendering
3. Using useId() hook inside conditionally rendered loops, which produces different ID sequences between server and client renders
4. Array keys based on index position when the array order differs between server and client due to async data fetching
5. Keys dependent on user preferences, theme, or locale that differ between server defaults and client-side values
6. CSS-in-JS libraries generating different class name hashes on server vs client due to missing configuration
7. Conditional rendering logic that evaluates differently on server (typeof window !== "undefined") affecting which elements receive keys
8. Keys generated from data that changes between server render time and client hydration time

How to fix "Warning: Prop `key` did not match"

Warning: Prop `key` did not match. Server: "item-1234" Client: "item-5678"
    in li (at ListComponent.tsx:15)
    in ul (at ListComponent.tsx:12)

// ❌ BAD: Random keys differ between server and client
{items.map(item => (
  <div key={Math.random()}>{item.name}</div>
))}

// ❌ BAD: Timestamp keys differ
{items.map(item => (
  <div key={`${item.id}-${Date.now()}`}>{item.name}</div>
))}

// ✅ GOOD: Use stable, deterministic keys
{items.map(item => (
  <div key={item.id}>{item.name}</div>
))}

'use client';
import { useState, useEffect } from 'react';

function UserPreferencesList({ items }) {
  const [mounted, setMounted] = useState(false);

  useEffect(() => {
    setMounted(true);
  }, []);

  // During SSR and initial hydration, use server-safe keys
  if (!mounted) {
    return (
      <ul>
        {items.map(item => (
          <li key={item.id}>{item.name}</li>
        ))}
      </ul>
    );
  }

  // After hydration, safe to use localStorage
  const savedOrder = localStorage.getItem('itemOrder');
  const sortedItems = sortByPreference(items, savedOrder);

  return (
    <ul>
      {sortedItems.map(item => (
        <li key={item.id}>{item.name}</li>
      ))}
    </ul>
  );
}

// ❌ BAD: useId() in conditional loop causes ID sequence mismatch
function BadList({ items, showDetails }) {
  return (
    <ul>
      {items.map(item => {
        const id = useId(); // Different IDs on server vs client!
        return showDetails ? (
          <li key={id}>{item.name}</li>
        ) : null;
      })}
    </ul>
  );
}

// ✅ GOOD: Extract component so useId() is called consistently
function ListItem({ item }) {
  const id = useId();
  return <li key={id}>{item.name}</li>;
}

function GoodList({ items, showDetails }) {
  return (
    <ul>
      {items.filter(() => showDetails).map(item => (
        <ListItem key={item.id} item={item} />
      ))}
    </ul>
  );
}

// In Next.js, use consistent data fetching
export async function generateStaticParams() {
  const items = await fetchItems();
  return items.map(item => ({ id: item.id }));
}

export default async function Page({ params }) {
  // Fetch the same data on the server
  const items = await fetchItems();

  return (
    <ul>
      {items.map(item => (
        <li key={item.id}>{item.name}</li>
      ))}
    </ul>
  );
}

function SessionBasedList({ items }) {
  const sessionKey = typeof window !== 'undefined'
    ? sessionStorage.getItem('sessionId')
    : 'server-session';

  return (
    <ul suppressHydrationWarning>
      {items.map(item => (
        <li key={`${sessionKey}-${item.id}`} suppressHydrationWarning>
          {item.name}
        </li>
      ))}
    </ul>
  );
}

# Next.js
npm run build
npm run start

# Then test the affected pages in your browser

Advanced notes

Frequently asked questions

What does "Warning: Prop `key` did not match" mean?

This warning is a React hydration error that occurs during server-side rendering (SSR) when the key prop assigned to an element on the server doesn't match the key prop React expects during client-side hydration. Hydration is the process where React converts pre-rendered HTML from the server into a fully interactive application by attaching event handlers and reconciling the virtual DOM. React expects the server-rendered HTML and the initial client render to be identical, including all props like key.

How do I fix "Warning: Prop `key` did not match"?

This hydration warning occurs when the key prop on a React element differs between server-side rendering and client-side hydration. It typically happens with dynamic content, unstable key generation, or browser-only logic that runs during initial render.

What causes "Warning: Prop `key` did not match"?

Using non-deterministic values for keys like Math.random(), Date.now(), or crypto.randomUUID() that generate different values on server and client Generating keys based on browser-only APIs (window, localStorage, sessionStorage) that are undefined during server-side rendering Using useId() hook inside conditionally rendered loops, which produces different ID sequences between server and client renders

Is the "Warning: Prop `key` did not match" error serious?

It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Related errors

• Warning: Each child in a list should have a unique "key" prop.

  How to fix "Each child in a list should have a unique key prop" in React

  HIGH

• JSX transform failed

  How to fix "JSX transform failed" in React

  HIGH

• Keys should not be passed as JSX attributes

  How to fix "Keys should not be passed as JSX attributes" in React

  MEDIUM

• Unexpected token <

  Unexpected token < (JSX syntax error)

  HIGH

• Failed to resolve import. Does the file exist?

  How to fix "Failed to resolve import" in React

  HIGH

• npm ERR! code ETIMEDOUT npm ERR! network request to https://registry.npmjs.org timed out

  npm registry request timed out

  MEDIUM

Official resources & further reading

• 📚React Official Documentation
• 📖
  React: hydrateRoot API Reference(Official Docs)
• 📖
  Next.js: Text content does not match server-rendered HTML(Official Docs)
• Ben Ilegbodu: Handling the React Server Hydration Mismatch Error
• 🐙
  React Issue #33779: useId() causes hydration mismatch in conditional loops(GitHub)
• PropelAuth: Understanding Hydration Errors by Building a SSR React Project
• Craig Morten: Escaping React Hydration Error Hell
• Kaivlya: Understanding React Hydration Errors
• Next.js Discussion #35773: Hydration failed because initial UI does not match