How do you diagnose and fix hydration mismatches in Vue SSR / Nuxt 3?

Q: How do you diagnose and fix hydration mismatches in Vue SSR / Nuxt 3?

**Target Audience:** Developers running Vue SSR or Nuxt who see hydration warnings and need a method, not guesswork. Assumes you know what SSR is. **Difficulty:** Hard > **How to read this doc:** Ideas are explained in plain language first, then tagged with 📌 Interview term: so you also learn the words an interviewer listens for. Every warning quoted here is real output. The plain-Vue cases were server-rendered with @vue/server-renderer 3.5.44 and hydrated in jsdom with createSSRApp . The Nuxt cases come from a Nuxt 4.6.1 app (Vue 3.5.44) that was built, run with nuxt dev and as a production server, and loaded in headless Chromium. Nuxt 3 itself was **not** installed; see section 8 for why the same advice applies. ## 1. Why This Even Matters — A Story First A museum ships a giant jigsaw puzzle already assembled and glued to a board. When it arrives, a curator walks along the board with the picture on the box and sticks a little lab

The problem

Question presented to candidate: "After we moved our Nuxt app to SSR, the console shows 'Hydration completed but contains mismatches' on some pages, and a dark-mode class sometimes appears wrong. How do you find out what is mismatching, and how do you fix it properly rather than just hiding the warning?"

What a strong answer should cover:

What a mismatch is: the first client render does not produce the HTML the server sent, so hydration cannot simply adopt the DOM.
Reading the dev warning: the type (text, children, class, style, attribute, node), the server value vs the client value, and the component trace.
Typical causes: Date/Math.random(), window/localStorage in setup, locale or time-zone formatting, missing state transfer, and invalid HTML nesting that the browser parser rewrites.
What Vue does about it: text and node mismatches are patched, while class, style and attribute mismatches are check-only and stay wrong in production.
The fixes: move browser-only work to onMounted, useId() for IDs, transfer state (useState/useFetch in Nuxt), <ClientOnly>, and data-allow-mismatch only for genuinely expected differences.
Production diagnostics: __VUE_PROD_HYDRATION_MISMATCH_DETAILS__, or debug: { hydration: true } in Nuxt.

Clarifying questions expected:

"Does it happen in development too, or only in production builds?"
"Is the differing value user-specific (theme, locale, time zone) or random?"

Code / implementation expected: Optional — a component that renders a neutral value on the server and fills in a browser-only value in onMounted.

ssr
hydration
mismatch

Try it yourself

Sketch your approach before you read the solution. That is what the interview tests.

Stuck? Get a hint.

A short nudge toward the approach. It will not give the answer away.

Solution

Target Audience: Developers running Vue SSR or Nuxt who see hydration warnings and need a method, not guesswork. Assumes you know what SSR is. Difficulty: Hard

How to read this doc: Ideas are explained in plain language first, then tagged with 📌 Interview term: so you also learn the words an interviewer listens for. Every warning quoted here is real output. The plain-Vue cases were server-rendered with @vue/server-renderer 3.5.44 and hydrated in jsdom with createSSRApp. The Nuxt cases come from a Nuxt 4.6.1 app (Vue 3.5.44) that was built, run with nuxt dev and as a production server, and loaded in headless Chromium. Nuxt 3 itself was not installed; see section 8 for why the same advice applies.

1. Why This Even Matters — A Story First

A museum ships a giant jigsaw puzzle already assembled and glued to a board. When it arrives, a curator walks along the board wit

The solution is hidden so you can try first

14 min read · 12 sections

Read the code

VueHydration-safe patterns: onMounted for browser values, data-allow-mismatch, useId

Open in playground

<script setup>
import { ref, onMounted, useId } from "vue";

// 1. Browser-only value: start with something the server can render too,
//    then switch to the real value after mount (onMounted never runs on the server).
const width = ref(null);
onMounted(() => { width.value = window.innerWidth; });

// 2. A value that legitimately differs (a timestamp): render it, but tell Vue
//    the text mismatch is expected with data-allow-mismatch.
const renderedAt = new Date().toISOString().slice(11, 19);

// 3. IDs that must match on both sides: useId() is deterministic per component position.
const emailId = useId();
</script>

<template>
  <p>Viewport width: {{ width === null ? "measuring..." : width + "px" }}</p>
  <p data-allow-mismatch="text">Rendered at {{ renderedAt }}</p>
  <label :for="emailId">Email</label>
  <input :id="emailId" type="email" />
</template>

VueNuxt page with useState, onMounted and ClientOnly (built and checked on Nuxt 4.6.1)

<script setup lang="ts">
// Nuxt page: three hydration-safe patterns (ref, onMounted, useState and ClientOnly are auto-imported).

// 1. Shared state created on the server and serialised into the payload:
//    the client reuses the server value instead of computing a new one.
const greeting = useState("greeting", () => (import.meta.server ? "Hello from the server" : "never used"));

// 2. Browser-only data: render a neutral value first, fill it in after mount.
const tz = ref("");
onMounted(() => { tz.value = Intl.DateTimeFormat().resolvedOptions().timeZone; });
</script>

<template>
  <main>
    <p class="greeting">{{ greeting }}</p>
    <p class="tz">Your time zone: {{ tz || "detecting..." }}</p>
    <!-- 3. A widget that cannot render on the server at all -->
    <ClientOnly>
      <p class="widget">browser-only widget</p>
      <template #fallback><p class="widget">loading widget</p></template>
    </ClientOnly>
  </main>
</template>

Discussion

Other approaches, follow-ups and how it went in real interviews.

Sign in to join the discussion.

No comments yet. Share how you would answer it.

The solution is hidden so you can try first

Keep your momentum going.