Fix the Next.js hydration error from new Date(), toLocaleString() and Math.random()

A client component renders once on the server and again in the browser, and a date, a locale format or a random number comes out different the second time, so React throws a hydration error. This page is the code side: format on the server with a pinned time zone, switch to local time after hydration, a ticking clock that waits for mount, a random pick made once on the server, and ssr: false as the last resort.

One payment$9

By buying you agree to the Terms.

One payment, no subscription
Download right after paying
Use it in client projects
Won't run on the listed stack? We fix it or refund you

Ready forCursorv0Lovableshadcn CLI

Full product pageReact · Tailwind · TypeScript

Fix 1: format the date on the server

app/orders/page.tsx (Server Component)

import { OrderRow } from "./order-row";

// Format dates on the server with a pinned time zone and locale, then pass
// plain strings down. The browser never re-computes them, so nothing can differ.
const fmt = new Intl.DateTimeFormat("en-US", {
  dateStyle: "medium",
  timeStyle: "short",
  timeZone: "UTC",
});

type Order = { id: string; createdAt: string };

export default async function OrdersPage() {
  const orders: Order[] = await getOrders();
  return (
    <ul>
      {orders.map((o) => (
        <OrderRow key={o.id} id={o.id} created={fmt.format(new Date(o.createdAt)) + " UTC"} />
      ))}
    </ul>
  );
}

async function getOrders(): Promise<Order[]> {
  return [{ id: "a1", createdAt: "2026-10-27T08:00:00Z" }]; // your data here
}

app/orders/order-row.tsx

"use client";

export function OrderRow({ id, created }: { id: string; created: string }) {
  // A string from the server renders the same on both passes.
  return (
    <li className="flex justify-between">
      <span>{id}</span>
      <time>{created}</time>
    </li>
  );
}

Good to know

"use client" doesn't skip the server. A Client Component is still rendered to HTML on the server and then hydrated, so anything that reads the clock, the locale or a random source can render two different strings.
The server usually runs in UTC with an en-US locale, and the browser runs in the visitor's time zone and language. That is why toLocaleString() breaks even when no time has passed.
suppressHydrationWarning on the element hides the warning for that one text node. It doesn't make the two renders agree, so the visitor can still see the server's text flash before React patches it. Keep it for a single timestamp you are fine with.
What we ran on October 27, 2026: every file on this page type-checks with TypeScript 5.9.3 against @types/react 19.3.0, react 19.1.1 and next 15.5.28. Passing a Date object to OrderRow, giving ssr a string and a plan object with a missing field all fail the same check. We didn't run these exact files in a browser on this page; the five fixes were run in next dev, next build and next start for our blog post.

Fix 2: show local time after hydration

When people need their own time zone, render a fallback first and switch after hydration. useSyncExternalStore does that without a setState inside useEffect: the server and the first browser pass use getServerSnapshot, then React re-renders with the browser value.

components/local-time.tsx

"use client";
import { useSyncExternalStore } from "react";

const subscribe = () => () => {};

// Server and the first browser pass both render the fallback (getServerSnapshot),
// then React switches to the browser value right after hydration. No mismatch,
// and no setState inside useEffect.
export function LocalTime({ iso, fallback }: { iso: string; fallback: string }) {
  const text = useSyncExternalStore(
    subscribe,
    () => new Date(iso).toLocaleString(),
    () => fallback,
  );
  return <time dateTime={iso}>{text}</time>;
}

Fix 3: a ticking clock waits for mount

A clock changes every second, so no server value can match it. Start with null, render a placeholder of the same width, and set the time in useEffect. tabular-nums keeps the digits from shifting the layout.

components/live-clock.tsx

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

// A ticking clock: render nothing time-based until the browser has mounted.
export function LiveClock() {
  const [now, setNow] = useState<Date | null>(null);
  useEffect(() => {
    const tick = () => setNow(new Date());
    tick();
    const id = setInterval(tick, 1000);
    return () => clearInterval(id);
  }, []);
  return <span className="tabular-nums">{now ? now.toLocaleTimeString() : "--:--:--"}</span>;
}

Fix 4: pick the random value once, on the server

Math.random() in a Client Component gives the server one number and the browser another. Pick it in the Server Component and pass it down as a prop, so both renders use the same value.

app/promo/page.tsx

// app/promo/page.tsx (Server Component): pick the random value once, here.
import { randomInt } from "node:crypto";
import { PromoCard } from "./promo-card";

export const dynamic = "force-dynamic"; // a new pick per request

export default function Page() {
  const pick = randomInt(0, 3);
  return <PromoCard variant={pick} />;
}

app/promo/promo-card.tsx

"use client";

const headlines = ["Ship it today", "Built for Next.js", "Copy, paste, done"];

export function PromoCard({ variant }: { variant: number }) {
  // The client gets the same number the server used, so the text matches.
  return <h2 className="text-2xl font-semibold">{headlines[variant]}</h2>;
}

Fix 5: ssr: false for a widget that can't match

Some widgets read the clock or window on every render, like a live chart. Load them with next/dynamic and ssr: false from inside a Client Component and give them a loading box of the same size. You lose server HTML for that part, so use it for the widget, not the page.

components/chart-slot.tsx

"use client";
import dynamic from "next/dynamic";

// Last resort for a widget that reads the clock or window on every render:
// skip server rendering for it. ssr: false only works inside a Client Component.
const LiveChart = dynamic(() => import("./live-chart"), {
  ssr: false,
  loading: () => <div className="h-64 animate-pulse rounded-xl bg-zinc-900" />,
});

export function ChartSlot() {
  return <LiveChart />;
}

Where Analytics Dashboard V1 fits

Dashboards are where this error shows up most: "updated 2 minutes ago", chart axes in the visitor's locale, live numbers. Analytics Dashboard V1 is a full animated dashboard you feed from your own data, so you can format the dates in a Server Component the way Fix 1 does and pass the finished strings in.
If you only want free pieces with source first, the free kit is MIT.

The free kit: Toast Stack, Pricing Switch, Upload Dropzone and more, MIT

Install

Copy from the zipPut react/src/components into src/, then none. Next.js App Router and React 19.
Or ask your AIPaste PROMPT.md into Cursor, Lovable or v0.

Props

data: your KPIs and series
title / subtitle: header text
startDelay: ms before the count-up

How qodesign compares

qodesign vs shadcnblocksshadcnblocks is best for: assembling whole pages from ready-made sections.
qodesign vs Kokonut UIKokonut UI is best for: landing page sections and templates installed by an AI agent.
qodesign vs TremorTremor is best for: dashboards and charts: area, bar, line and donut charts, trackers, KPI cards, tables.

All comparisons, with prices read on each library's own site.

From the blog: Next.js Hydration Error from Dates: 5 Tested Fixes

From the blog: useSyncExternalStore getServerSnapshot: Next.js Fix

Questions

Why does new Date() cause a hydration error in Next.js?

The component renders on the server and again in the browser, a moment later and often in another time zone. The two strings differ and React reports the mismatch.

Does "use client" stop server rendering?

No. Client Components are still rendered to HTML on the server. "use client" only means they also run in the browser.

Is suppressHydrationWarning a fix?

It silences the warning for one text node. The server text can still flash before React replaces it, so it suits a single timestamp, not a whole widget.

Can I use ssr: false in a Server Component?

No. In the App Router, next/dynamic with ssr: false only works inside a Client Component.

Does the dashboard work in Next.js?

Yes, as a client component. Keep "use client" at the top of the file that renders it, as in the snippet above. App Router and Pages Router both work.

Can Cursor or v0 add it for me?

Yes. Each download has a PROMPT.md. Paste it into Cursor, Lovable, v0 or Claude Code and it fits the piece into your app.

Can I use it in client work?

Yes, in personal and client projects. You can't resell the code itself as a kit.