Debugging unexpected UI behavior in v0 apps

Why V0 apps show unexpected UI behavior

V0 generates Next.js App Router code where components are Server Components by default. This means they render on the server first, then hydrate on the client. When V0-generated code accesses browser-only APIs (window, localStorage, document) during the server render, the server output differs from the client output, causing hydration mismatches. These mismatches manifest as content flickering, elements appearing in the wrong position, event handlers not working, or components rendering different content than expected.

• Hydration mismatch — server HTML differs from client-rendered HTML due to browser API access
• Accessing localStorage or window during server-side rendering causes ReferenceError or different output
• Missing 'use client' directive on components that use hooks, event handlers, or browser APIs
• Date/time rendering that differs between server timezone and client timezone
• V0 preview sandbox rendering differently from Vercel production due to different runtime environments

Error messages you might see

Before you start

• A V0 project experiencing flickering, broken events, or rendering inconsistencies
• Browser developer tools with console open
• Understanding of the difference between Server and Client Components

How to fix it

'use client';
import { useState } from 'react';
export function Greeting() {
  // Causes hydration mismatch — localStorage is read during render
  const [name] = useState(localStorage.getItem('userName') || 'Guest');
  return <h1>Welcome, {name}</h1>;
}

'use client';
import { useState, useEffect } from 'react';
export function Greeting() {
  const [name, setName] = useState('Guest');
  useEffect(() => {
    const stored = localStorage.getItem('userName');
    if (stored) setName(stored);
  }, []);
  return <h1>Welcome, {name}</h1>;
}

// Missing 'use client' — onClick handler silently fails
import { useState } from 'react';
import { Button } from '@/components/ui/button';
export function Counter() {
  const [count, setCount] = useState(0);
  return <Button onClick={() => setCount(count + 1)}>Count: {count}</Button>;
}

'use client';
import { useState } from 'react';
import { Button } from '@/components/ui/button';
export function Counter() {
  const [count, setCount] = useState(0);
  return <Button onClick={() => setCount(count + 1)}>Count: {count}</Button>;
}

// Chart component crashes during SSR
import { LineChart } from './LineChart';
export default function Dashboard() {
  return <LineChart data={chartData} />;
}

import dynamic from 'next/dynamic';
const LineChart = dynamic(() => import('./LineChart'), {
  ssr: false,
  loading: () => <div className="h-64 animate-pulse bg-muted rounded" />,
});
export default function Dashboard() {
  return <LineChart data={chartData} />;
}

Complete code example

1'use client';
2
3import { useState, useEffect, type ReactNode } from 'react';
4
5interface ClientSafeWrapperProps {
6  children: ReactNode;
7  fallback?: ReactNode;
8}
9
10/**
11 * Wrapper component that only renders children after
12 * client-side hydration is complete. Use this to wrap
13 * any component that depends on browser APIs.
14 */
15export function ClientSafeWrapper({
16  children,
17  fallback = null,
18}: ClientSafeWrapperProps) {
19  const [isMounted, setIsMounted] = useState(false);
20
21  useEffect(() => {
22    setIsMounted(true);
23  }, []);
24
25  if (!isMounted) {
26    return <>{fallback}</>;
27  }
28
29  return <>{children}</>;
30}
31
32// Usage example:
33// <ClientSafeWrapper fallback={<Skeleton className="h-10" />}>
34//   <ComponentThatUsesLocalStorage />
35// </ClientSafeWrapper>

Best practices to prevent this

• Always check the browser console for hydration warnings — they pinpoint the exact mismatch
• Never access localStorage, window, or document during component render — use useEffect instead
• Add 'use client' as the very first line of files that use hooks, event handlers, or browser APIs
• Initialize state with server-safe defaults that match what the server will render
• Use dynamic imports with ssr: false for components that cannot render on the server at all
• Avoid using Date.now() or Math.random() in render functions — they produce different values on server and client
• Test components in both the V0 preview and after deploying to catch environment-specific rendering differences
• Use a ClientSafeWrapper component to guard browser-dependent UI sections

Still stuck?

Copy one of these prompts to get a personalized, step-by-step explanation.

Related error patterns

Explore related guides

Guides from other topics that help with this issue