Nuxt•2mo ago

Hydration hell - A simple loading state on a Nuxt UI button

Hi, I have a UButton from Nuxt UI for which I set the loading prop to true initially, then onMounted I switch it to false. This gives me a hydration error and I can't understand why. My actual use case is more complicated that the example I'm sharing, as it involves a state from Pinia and when loaded I put the buttons loading off. But even if I strip away all the state things and have just a button with a loading state which turns of when mounted, I'm facing problems. Button:

<UButton
  :loading="loading"
  label="User"
/>

<UButton
  :loading="loading"
  label="User"
/>

Script:

<script lang="ts" setup>
  const loading = ref(true);

  onMounted(async () => {
    loading.value = false;
  });
</script>

<script lang="ts" setup>
  const loading = ref(true);

  onMounted(async () => {
    loading.value = false;
  });
</script>

55 Replies

kapa.ai•2mo ago

Hi @ObSeSSeN. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave: ---------------------- You're experiencing a hydration mismatch error because the initial state of your button differs between server-side rendering and client-side hydration. This is a common issue in Nuxt applications with SSR. Why This Happens When using Nuxt with SSR, your page is rendered twice: 1. First on the server (with loading: true) 2. Then on the client during hydration The problem occurs because you're changing the loading state in onMounted(), which only runs on the client side. This creates a mismatch between what was rendered on the server and what Vue expects during hydration. As explained in a Stack Overflow post about hydration mismatches:

In Nuxt SSR the page is generated twice - first it is statically pre-rendered on server, then second time it is being "hydrated" with JavaScript features on client. Stack Overflow

Solutions 1. Use useNuxtApp().isHydrating You can check if the app is currently hydrating and conditionally set the initial state:

<script lang="ts" setup>
const nuxtApp = useNuxtApp()
const loading = ref(!import.meta.client || nuxtApp.isHydrating)

onMounted(() => {
  loading.value = false
})
</script>

<script lang="ts" setup>
const nuxtApp = useNuxtApp()
const loading = ref(!import.meta.client || nuxtApp.isHydrating)

onMounted(() => {
  loading.value = false
})
</script>

The isHydrating property helps you detect when the app is in the hydration phase, as documented in Nuxt docs. 2. Use useState() for SSR-compatible state Another approach is to use Nuxt's useState() composable which is designed to handle state that needs to be consistent between server and client:

<script lang="ts" setup>
const loading = useState('buttonLoading', () => true)

onMounted(() => {
  loading.value = false
})
</script>

<script lang="ts" setup>
const loading = useState('buttonLoading', () => true)

onMounted(() => {
  loading.value = false
})
</script>

3. Use useLoadingIndicator() For more complex loading states, you might consider using Nuxt's built-in loading indicator:

<script lang="ts" setup>
const loadingIndicator = useLoadingIndicator()
loadingIndicator.isLoading.value = true

onMounted(() => {
  loadingIndicator.isLoading.value = false
})
</script>

<script lang="ts" setup>
const loadingIndicator = useLoadingIndicator()
loadingIndicator.isLoading.value = true

onMounted(() => {
  loadingIndicator.isLoading.value = false
})
</script>

This is documented in the Nuxt docs for useLoadingIndicator. Best Practice The most reliable approach is to ensure your initial state is the same on both server and client. If you need different states, use client-only components or the techniques mentioned above to handle the transition properly. For your specific case with Pinia, you might want to consider initializing your store in a way that's consistent between server and client, or use useState() to manage the loading state separately from your Pinia store. I hope this helps resolve your hydration issues! ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•2mo ago

<@519787352944672780> Kapa.ai is still learning and improving, please let me know how I did by reacting below.

ObSeSSeNOP•2mo ago

1. Use useNuxtApp().isHydrating - does not work, same problem 2. Use useState() for SSR-compatible state - does not work, same problem This is the console log:

[Vue warn]: Hydration attribute mismatch on 
<button class="rounded-[calc(var(--ui-r…:outline-(--ui-primary)" type="button" data-v-inspector="node_modules/@nuxt/ui/di…nents/LinkBase.vue:43:3"> 
  - rendered on server: (not rendered)
  - expected on client: disabled="true"

[Vue warn]: Hydration attribute mismatch on 
<button class="rounded-[calc(var(--ui-r…:outline-(--ui-primary)" type="button" data-v-inspector="node_modules/@nuxt/ui/di…nents/LinkBase.vue:43:3"> 
  - rendered on server: (not rendered)
  - expected on client: disabled="true"

johntanzer•2mo ago

Hey! The hydration log you giving is not for the example you provided in orignal post. do you mind sharing hydration log from original post

ObSeSSeNOP•2mo ago

Sorry, I recreated the problem and this is the whole page code:

<template>
  <div>
    <UButton :loading="loading">Click me</UButton>
  </div>
</template>

<script lang="ts" setup>
  const loading = useState('buttonLoading', () => true);

  onMounted(() => {
    loading.value = false;
  });
</script>

<template>
  <div>
    <UButton :loading="loading">Click me</UButton>
  </div>
</template>

<script lang="ts" setup>
  const loading = useState('buttonLoading', () => true);

  onMounted(() => {
    loading.value = false;
  });
</script>

And this is the error for it:

[Vue warn]: Hydration attribute mismatch on 
<button class="rounded-[calc(var(--ui-r…:outline-(--ui-primary)" type="button" data-v-inspector="node_modules/@nuxt/ui/di…nents/LinkBase.vue:43:3"> 
  - rendered on server: (not rendered)
  - expected on client: disabled="true"

[Vue warn]: Hydration attribute mismatch on 
<button class="rounded-[calc(var(--ui-r…:outline-(--ui-primary)" type="button" data-v-inspector="node_modules/@nuxt/ui/di…nents/LinkBase.vue:43:3"> 
  - rendered on server: (not rendered)
  - expected on client: disabled="true"

johntanzer•2mo ago

Yes this makes sense it is a mismatch! can you try this and let me know if you get error

 if (import.meta.client && !nuxtApp.isHydrating) {
    // Only change the state after hydration is complete
    loading.value = false;
  }

 if (import.meta.client && !nuxtApp.isHydrating) {
    // Only change the state after hydration is complete
    loading.value = false;
  }

sorry and obv set const nuxtApp = useNuxtApp();

ObSeSSeNOP•2mo ago

Well this is strange... With the following code it newer goes out of the loading state if I refresh the page.

<template>
  <div>
    <UButton :loading="loading">Click me</UButton>
  </div>
</template>

<script lang="ts" setup>
  const loading = ref(true);
  const nuxtApp = useNuxtApp();

  onMounted(() => {
    if (import.meta.client && !nuxtApp.isHydrating) {
      console.log('hydrated');
      // Only change the state after hydration is complete
      loading.value = false;
    }
  });
</script>

<template>
  <div>
    <UButton :loading="loading">Click me</UButton>
  </div>
</template>

<script lang="ts" setup>
  const loading = ref(true);
  const nuxtApp = useNuxtApp();

  onMounted(() => {
    if (import.meta.client && !nuxtApp.isHydrating) {
      console.log('hydrated');
      // Only change the state after hydration is complete
      loading.value = false;
    }
  });
</script>

johntanzer•2mo ago

try take it out of the onmounted

ObSeSSeNOP•2mo ago

Same thing 🙈

johntanzer•2mo ago

what it doesnt stop loading state?

ObSeSSeNOP•2mo ago

No, and I put a console log in it and don't see the log in the console after the page stops loading

johntanzer•2mo ago

ahh wait have you tried this

onMounted(() => {
  if (import.meta.client) {
    nextTick(() => {
      loading.value = false;
      console.log('hydration complete, loading set to false');
    });
  }
});

onMounted(() => {
  if (import.meta.client) {
    nextTick(() => {
      loading.value = false;
      console.log('hydration complete, loading set to false');
    });
  }
});

ObSeSSeNOP•2mo ago

With this I'm back at the hydration error:

[Vue warn]: Hydration attribute mismatch on 
<button class="rounded-[calc(var(--ui-r…:outline-(--ui-primary)" type="button" data-v-inspector="node_modules/@nuxt/ui/di…nents/LinkBase.vue:43:3"> 
  - rendered on server: (not rendered)
  - expected on client: disabled="true"

[Vue warn]: Hydration attribute mismatch on 
<button class="rounded-[calc(var(--ui-r…:outline-(--ui-primary)" type="button" data-v-inspector="node_modules/@nuxt/ui/di…nents/LinkBase.vue:43:3"> 
  - rendered on server: (not rendered)
  - expected on client: disabled="true"

johntanzer•2mo ago

yeah something strange - i dont get any hydration error

Omnislash•2mo ago

Since it's most likely the state, if your button has no SEO interest, I wouldn't bother and either : - put the button in a <ClientOnly> (https://nuxt.com/docs/api/components/client-only) - ignore this mismatch (I forgot how to do so)

ObSeSSeNOP•2mo ago

Well I don't get an error in chrome 🤦‍♂️

johntanzer•2mo ago

prop best to share s stakckblit repro to show how you get error not nessacry this does almmost same thing and useState is ssr freindly ❤️ this should never give a hydration error since it is being done only agter conplete page hydratin!

ObSeSSeNOP•2mo ago

So, Firefox gives me an error, but Chrome works fine... What could be causing this discrepancy?

Omnislash•2mo ago

stupid sudden idea... did you install the heroicons ? could it be the favicon not loading quick enough if the default state is "loading" ? (which would be weird given what 's expected in the error XD)

ObSeSSeNOP•2mo ago

I have the following:

    "@iconify-json/carbon": "^1.2.8",
    "@iconify-json/game-icons": "^1.2.1",
    "@iconify-json/heroicons": "^1.2.2",
    "@iconify-json/lucide": "^1.2.28"

    "@iconify-json/carbon": "^1.2.8",
    "@iconify-json/game-icons": "^1.2.1",
    "@iconify-json/heroicons": "^1.2.2",
    "@iconify-json/lucide": "^1.2.28"

Omnislash•2mo ago

Other random idea, regarding the error.... Can you try adding :disabled="loading" on your button ?

ObSeSSeNOP•2mo ago

It gives me the same thing in FF... But I noticed something else, if I do a hard refresh in FF (CMD+Shift+R) it loads fine. If I then do a normal refresh (CMD+R) it gives me the error. 😕

Omnislash•2mo ago

I have no other idea sorry:/ I still think if nothing but about client state, you could still wrap it in <ClientOnly> in the meantime and create an issue on github

ObSeSSeNOP•2mo ago

But this happens for me on a lot of different components around the page... I'm not sure I should be wrapping them all in <ClientOnly>

Omnislash•2mo ago

Definitely not then ^^"""

ObSeSSeNOP•2mo ago

Anywhere I want to start from a loading state and then load the data through Pinia this happens. I was trying a million different things and then decided to do this simple example, wich also gave me the same error 🙈

Omnislash•2mo ago

@kapa.ai list the reason why I would have a hydration mismatch on a button state event when using useState to set it.

kapa.ai•2mo ago

Let me check the knowledge base for you again. One moment! :books: ---------------------- Even when using useState in Nuxt, you can still encounter hydration mismatches with button states. Here are the main reasons this might happen: Reasons for Hydration Mismatches with useState and Button States 1. Order of Component Rendering The order in which components are rendered during SSR can cause mismatches. If a component using the state is rendered before the state is initialized, it will have different values on server vs client.
As explained by a Nuxt contributor: "The order in which the components are called is as follows: app.vue -> TestHeader.vue -> (NuxtPage) -> index.vue. This means that header is rendered before index page and the value of testValue is undefined." Github Issue 2. State Modification During Rendering If you modify state during the rendering process, components rendered earlier won't reflect these changes on the server, but will update on the client.
"There is no reactive shared space on server - once the component is rendered it will not update!" Github Issue 3. Non-Serializable Data in State If your state contains data that can't be serialized to JSON (like functions, classes, or symbols), it won't transfer correctly from server to client.
"Because the data inside useState will be serialized to JSON, it is important that it does not contain anything that cannot be serialized, such as classes, functions or symbols." Nuxt Docs 4. Accessing Browser APIs in State Initialization If your state initialization accesses browser-only APIs (like localStorage), it will behave differently on server vs client. 5. Nested Refs Not Being Unwrapped Ref unwrapping in templates only applies to top-level properties. If your state is nested inside another object, you might need to use .value explicitly.
"Ref unwrapping in templates only applies if the ref is a top-level property in the template render context." Stack Overflow 6. Random or Time-Dependent Values If your state initialization includes random values or time-dependent calculations, they'll likely be different between server and client.
"The server calculates its own cDummy value and when it comes to browser, it calculates cDummy once again, which can be different." Stack Overflow 7. Modifying Props or Shared Data If you modify props or shared data that affects the button state, it can cause hydration mismatches.
"When you do data.shift() on a prop, you are modifying the data in parent component as well. So it is different during the first time Vue is mounting on server and the second when mounting on client." Stack Overflow To avoid these issues, ensure state is initialized before components that use it are rendered, use client-only components for browser-specific functionality, and make sure your state is serializable. I hope this helps clarify why you might still encounter hydration mismatches even when using useState! ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•2mo ago

<@305772639438503936> Kapa.ai is still learning and improving, please let me know how I did by reacting below.

Omnislash•2mo ago

@ObSeSSeN do you use page transition?

ObSeSSeNOP•2mo ago

Not sure what you mean... for this example I made a new page with a blank layout

Omnislash•2mo ago

like this in the app in nuxt.config :

 pageTransition: { name: 'page', mode: 'out-in' }

 pageTransition: { name: 'page', mode: 'out-in' }

there is some problem with display order with page transitions and layout, there is an issue about it i'm randomly thinking it could affect other stuff.... but it's cleary unlicky, that's the longest shot ever

ObSeSSeNOP•2mo ago

I don’t have that You guys said that you are not able to reproduce my issue…are you using Chrome or Firefox?

Omnislash•2mo ago

I'm outside rn Can you create a stackblitz ? It's the best to reproduce and avoid people having to create anything to try and reproduce It's free and you can create a nuxt 3 project right away

ObSeSSeNOP•2mo ago

Will do 👍 This will be a bigger problem than I thought.... I seem to be unable to setup Nuxt 3 in Stackblitz with Nuxt UI 3 which uses Tailwind 4 🙈

Omnislash•2mo ago

Might actually be interesting to see if you have the problem with nuxt ui 2

ObSeSSeNOP•2mo ago

I found a working playground with v2 and same problem there https://stackblitz.com/edit/nuxt-ui-ekwj75tb?file=app.vue

Omnislash•2mo ago

Nice, don't expect much but I'll have a look by the end of the morning ^^

ObSeSSeNOP•2mo ago

Thank you! Just someone sharing my two day madness will help me not go crazy 😅

Omnislash•2mo ago

Aha I know the feeling

ObSeSSeNOP•2mo ago

Just a not on how I'm viewing the issue. If I open the Stackblitz in Chrome, clear the console and refresh the preview everything is fine. If I do the same in Firefox I get a hydration error.

Omnislash•2mo ago

sorry no idea, that's kind of mysterious and funny best is probably to create an issue on github

ObSeSSeNOP•2mo ago

On which project do you think this should go - Nuxt or Nuxt UI? 🤔

Omnislash•2mo ago

good question, do you have the same comportment wihout nuxt ui ? like, if you have it even without the UCard and all (didnt try to remove it), maybe you can reproduce by create your own button component with a quick and dirty basic loading system ?

Kal•2mo ago

I'm able to replicate in Stackblitz FF; the page seemingly works fine however I do see a hydration warning in the console. In Chrome I see no hydration warning in the console. A next step: Just for fun, as a test, make your own button component that has zero dependencies. @ObSeSSeN What is your original environment? Local machine?

ObSeSSeNOP•2mo ago

@Kal Locally I’m using a MacBook Pro M1 and have the project setup with Nuxt 3, Nuxt UI 3 beta.2, Pinia, Supabase @Omnislash , @Kal I have put together a small example in StackBlitz (https://stackblitz.com/edit/nuxt-starter-3c8vwwjq) using a custom button component and switching its loading and disabled state in different sequences. I found that going from a loading state to a loaded state works fine in Chrome, but causes issues in Firefox when refreshing the page. Going from a loaded state to a loading state works fine in both. The only dependency used is Tailwind, which I would imagine should not make a difference. I also opened an issue on Nuxt here https://github.com/nuxt/nuxt/issues/31296

Kal•2mo ago

Good test; I see same results still

Kal•2mo ago

The FF hydration errors go away when simply removing the disabled attribute on the <button>. I wonder if it's related to this: Firefox behaves different than all browsers when it comes to caching of form element states (e.g. button disabled state). https://bugzilla.mozilla.org/show_bug.cgi?id=654072

654072 - form input state (including disabled state and other prope...

NEW (nobody) in Core - DOM: Forms. Last updated 2025-03-07.

Kal•2mo ago

This looks like a 10 year old unsolved issue in Firefox If this is the case, you probably want to look at somehow excluding the actual <button> from being cached; maybe there's an attribute to tell Firefox "hey, this isn't part of a form, so don't cache it's state". Or maybe a workaround involving a computed and a lifecycle (e.g. beforeOnMount/onMounted) such that FF's cached state is circumvented

ObSeSSeNOP•2mo ago

@Kal you are right, this seems to be a very related problem. If I do not disable the button when it is loading there is no hydration error for that button in FF 🙈 I updated the StackBlitz with a second set of test buttons that use a custom component that is exactly the same as the first one, but does not disable the button when loading = true

Kal•2mo ago

You should focus on that thread or any other discussion online; for sure there has to be a workaround after so many years. I would probably look for something about excluding elements from Firefox's form caching

EmanueleDB•2mo ago

Did you try to wrap the button in a <ClientOnly> ?

Kal•2mo ago

Or perhaps make a computed that outputs false by default, but if client is true, then it's the full logic (state of loading or disabled prop)

Kyllian•2mo ago

just await nextTick might help

Kal•2mo ago

Ohhh good one lol, yes

Gaming

Programming

Hydration hell - A simple loading state on a Nuxt UI button

Did you find this page helpful?