Fix: Hydration failed because the initial UI does not match what was rendered on the server

export const IncorrectComponent = () => {
  return (
    <table>
      tbody is needed inside a table
    </table>
  )
}

Images inside an anchor tag throw an error too.

export const IncorrectComponent = () => {
  return (
    <a>
      <img />
    </a>
  )
}

Locale objects

When working with locale objects, like date or time objects that are being rendered in the component, it could lead to a mismatch in the output of the component. Who doesn’t love timezones, right?

export const IncorrectComponent = () => {
  return (
    {new Date().toLocaleString()}
  )
}

Incorrect CSS formatting

Incorrect CSS formatting can also lead to the error. For example, if you forget to add quotes when specifying background image

.image {
  background-image: url(https://www.wisdomgeek.com)
}

Extensions

Another possible reason is that an extension might be inserting something in the client page that might lead to this error since the rendered HTML is different than what the server sent.

Accessing the window object

If our component tries to access the window object, that is not going to be available on the server. That can lead to this error. This is pretty common when using a third-party component. Even checks like typeof window !== 'undefined' can lead to this error.

Sometimes you still need to access some of the properties mentioned above and there is no workaround. For those cases, there are a couple of possible solutions to fix it. Let us take a look at those next.

Potential workaround solutions

Use a useEffect to run only on the client side

We can intentionally render something different on the client side by using a variable that gets updated inside a useEffect hook.

import { useState, useEffect } from 'react'

export default function App() {
  const [isClient, setIsClient] = useState(false)

  useEffect(() => {
    setIsClient(true);
  }, [])

  return (
    <>
      {isClient && <>{/* Window related checks or components can go here */}</>}
      {!isClient && "Pre-rendered content"}
    </>
  )
}

Disable SSR

Another potential solution is to disable prerendering altogether for a component. In Next.js, we can do so using the following:

import dynamic from 'next/dynamic'

const DynamicComponent = dynamic(() => import('./Component'), { ssr: false })

export default NewComponent = () => {
  return (
    <>
      <DynamicComponent />
    </>
  )
}

Use suppressHydrationWarning

We can suppress the warning altogether by adding the HTML attribute suppressHydrationWarning to the component or element. For example, if we have a custom component that we want to suppress the warning for:

export default Component = () => {
  return (
    <>
      <CustomComponent suppressHydrationWarning={true} />
    </>
  );
}

And those are all the potential solutions for fixing the “Hydration failed because the initial UI does not match what was rendered on the server” error. Let us know in the comments if you are still facing the error.