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”.
Top comments (0)