suppressHydrationWarning. What is it?

#javascript #opensource #nextjs #node

You might have faced an error like “Hydration failed because the initial UI does not match what was rendered on the server.” So did shadcn-ui/ui. How can I be so sure? because they have suppressHydrationWarning attribute in the app/layout.tsx

I am making efforts to understand how shadcn-ui/ui is built and in this process, I saw suppressHydrationWarning in the app/layout.tsx.

I found this next.js documentation link: Text content does not match server-rendered HTML and it is quite insightful.

Why does hydration error occur?

When there is a mismatch between the React tree pre-rendered on server and the first rendered React tree in the browser, in other words, during hydration.

Hydration is when React converts the pre-rendered HTML from the server into a fully interactive application by attaching event handlers.

The following common causes are picked from the Next.js documentation

Common Causes

Hydration errors can occur from:

Incorrect nesting of HTML tags

<p> nested in another <p> tag
<div> nested in a <p> tag
<ul> or <ol> nested in a <p> tag
Interactive Content cannot be nested (<a> nested in a <a> tag, nested in a <button> tag, etc.)

2. Using checks like typeof window !== 'undefined' in your rendering logic

3. Using browser-only APIs like window or localStorage in your rendering logic

4. Using time-dependent APIs such as the Date() constructor in your rendering logic

Browser extensions modifying the HTML

6. Incorrectly configured CSS-in-JS libraries

Ensure your code is following our official examples

7. Incorrectly configured Edge/CDN that attempts to modify the html response, such as Cloudflare Auto Minify

Possible solutions:

There are three possible ways to fix the hydration error.

Solution 1: Using useEffect to run on the client only

Solution 2: Disabling SSR on specific components

Solution 3: Using suppressHydrationWarning

This stackoverflow question: How To Solve React Hydration Error in Next was solved by using the appropriate tbody tag in the table. Although #1 in common causes does not specifically point out that for table tag, hydration error might occur if you skip adding tbody, it is worth considering.

See Suppress Hydration Warning (React Docs):

If you set suppressHydrationWarning to true, React will not warn you about mismatches in the attributes and the content of that element. It only works one level deep, and is intended to be used as an escape hatch. Don’t overuse it. You can read more about hydration in the ReactDOM.hydrateRoot() documentation.

Conclusion:

Use suppressHydrationWarning as your last resort if you cannot resolve the issue by referring to common causes.

I said last resort because consider this sentence from the Next.js docs — “Sometimes content will inevitably differ between the server and client, such as a timestamp. You can silence the hydration mismatch warning by adding suppressHydrationWarning={true} to the element.”, it says “content will inevitably differ”.