Repository navigation
Flash of unstyled content with Mantine & mismatched initial UI #2589
Description
Which project does this relate to?
Start
Describe the bug
I am working on a project using the Mantine component library and am trying out Start. I have set up the basic Start configuration and a basic configuration of Mantine. When I visit the app URL in the browser, the app loads, but there are two problems.
- There is a brief flash of unstyled content.
- There is a warning message that "Hydration failed because the initial UI does not match what was rendered on the server." It also informs me that "Warning: Expected server HTML to contain a matching <script> in .".
I have included the full stacktraces below.
Warning: Expected server HTML to contain a matching
@mantine_core.js?v=e7ecb175:3546 Warning: Expected server HTML to contain a matching <script> in <div>.
at script
at ColorSchemeScript (http://localhost:3000/_build/node_modules/.vinxi/cache/client/deps/@mantine_core.js?v=e7ecb175:4157:3)
at Head (http://localhost:3000/_build/node_modules/.vinxi/cache/client/deps/@tanstack_start.js?v=e7ecb175:558:3)
at Html (http://localhost:3000/_build/node_modules/.vinxi/cache/client/deps/@tanstack_start.js?v=e7ecb175:544:3)
at RootDocument (http://localhost:3000/_build/app/routes/__root.tsx?t=1729351401814:54:25)
at RootComponent
at MatchInnerImpl (http://localhost:3000/_build/node_modules/.vinxi/cache/client/deps/chunk-AOWOSOBF.js?v=e7ecb175:3567:3)
at SafeFragment (http://localhost:3000/_build/node_modules/.vinxi/cache/client/deps/chunk-AOWOSOBF.js?v=e7ecb175:3487:87)
at SafeFragment (http://localhost:3000/_build/node_modules/.vinxi/cache/client/deps/chunk-AOWOSOBF.js?v=e7ecb175:3487:87)
at SafeFragment (http://localhost:3000/_build/node_modules/.vinxi/cache/client/deps/chunk-AOWOSOBF.js?v=e7ecb175:3487:87)
at MatchImpl (http://localhost:3000/_build/node_modules/.vinxi/cache/client/deps/chunk-AOWOSOBF.js?v=e7ecb175:3510:3)
at CatchBoundaryImpl (http://localhost:3000/_build/node_modules/.vinxi/cache/client/deps/chunk-AOWOSOBF.js?v=e7ecb175:1242:5)
at CatchBoundary (http://localhost:3000/_build/node_modules/.vinxi/cache/client/deps/chunk-AOWOSOBF.js?v=e7ecb175:1222:32)
at MatchesInner (http://localhost:3000/_build/node_modules/.vinxi/cache/client/deps/chunk-AOWOSOBF.js?v=e7ecb175:4147:19)
at SafeFragment (http://localhost:3000/_build/node_modules/.vinxi/cache/client/deps/chunk-AOWOSOBF.js?v=e7ecb175:3487:87)
at Matches (http://localhost:3000/_build/node_modules/.vinxi/cache/client/deps/chunk-AOWOSOBF.js?v=e7ecb175:4137:18)
at RouterContextProvider (http://localhost:3000/_build/node_modules/.vinxi/cache/client/deps/chunk-AOWOSOBF.js?v=e7ecb175:4233:3)
at RouterProvider (http://localhost:3000/_build/node_modules/.vinxi/cache/client/deps/chunk-AOWOSOBF.js?v=e7ecb175:4252:27)
at StartClient (http://localhost:3000/_build/node_modules/.vinxi/cache/client/deps/@tanstack_start.js?v=e7ecb175:713:14)
Hydration failed because the initial UI does not match what was rendered on the server.
Uncaught Error: Hydration failed because the initial UI does not match what was rendered on the server.
at throwOnHydrationMismatch (chunk-WMXHI54R.js?v=e7ecb175:9471:17)
at tryToClaimNextHydratableInstance (chunk-WMXHI54R.js?v=e7ecb175:9492:15)
at updateHostComponent (chunk-WMXHI54R.js?v=e7ecb175:14792:13)
at beginWork (chunk-WMXHI54R.js?v=e7ecb175:15933:22)
at HTMLUnknownElement.callCallback2 (chunk-WMXHI54R.js?v=e7ecb175:3672:22)
at Object.invokeGuardedCallbackDev (chunk-WMXHI54R.js?v=e7ecb175:3697:24)
at invokeGuardedCallback (chunk-WMXHI54R.js?v=e7ecb175:3731:39)
at beginWork$1 (chunk-WMXHI54R.js?v=e7ecb175:19763:15)
at performUnitOfWork (chunk-WMXHI54R.js?v=e7ecb175:19196:20)
at workLoopSync (chunk-WMXHI54R.js?v=e7ecb175:19135:13)
Followed by this message, no stacktrace.
Warning: An error occurred during hydration. The server HTML was replaced with client content in <div>.
There was an error while hydrating. Because the error happened outside of a Suspense boundary, the entire root will switch to client rendering.
Uncaught Error: There was an error while hydrating. Because the error happened outside of a Suspense boundary, the entire root will switch to client rendering.
at updateHostRoot (chunk-WMXHI54R.js?v=e7ecb175:14758:65)
at beginWork (chunk-WMXHI54R.js?v=e7ecb175:15931:22)
at beginWork$1 (chunk-WMXHI54R.js?v=e7ecb175:19751:22)
at performUnitOfWork (chunk-WMXHI54R.js?v=e7ecb175:19196:20)
at workLoopSync (chunk-WMXHI54R.js?v=e7ecb175:19135:13)
at renderRootSync (chunk-WMXHI54R.js?v=e7ecb175:19114:15)
at recoverFromConcurrentError (chunk-WMXHI54R.js?v=e7ecb175:18734:28)
at performConcurrentWorkOnRoot (chunk-WMXHI54R.js?v=e7ecb175:18682:30)
at workLoop (chunk-WMXHI54R.js?v=e7ecb175:195:42)
at flushWork (chunk-WMXHI54R.js?v=e7ecb175:174:22)
Your Example Website or App
https://stackblitz.com/edit/vitejs-vite-ig3cnf
Steps to Reproduce the Bug or Issue
I have tried to repro on Stackblitz, but I'm not sure that it supports Start. The repro is really quite simple though.
I have pushed a repro here: https://github.com/kennyjwilli/start-mantine-fouc.
pnpm ipnpm run dev- Visit http://localhost:3000 and observe the flash of unstyled content.
Expected behavior
As a user, I expect the content to be rendered with the correct initial styling, not flashing any unstyled content. I also expect no warnings in the browser console.
Screenshots or Videos
Kapture.2024-10-19.at.08.14.58.mp4
Platform
- OS: MacOS 14.6.1
- Browser: Chrome
- Version: 128.0.6613.138
Additional context
A key component to setting up Mantine with SSR is to add the ColorSchemeScript component to the head of the application (docs). In my example, I have done just that. Since I am using Start, the head of the app uses Head and looks like this:
<Head>
<ColorSchemeScript/>
<Meta/>
</Head>If I comment out ColorSchemeScript, the console warnings go away, but the flash of unstyled content remains.
Activity
ViliamKopecky commentedon Oct 20, 2024
I think they want you to link css files like this in loader:
As in example:
https://github.com/TanStack/router/blob/main/examples/react/start-trellaux/app/routes/__root.tsx#L17,L39
drew-dulgar commentedon Oct 22, 2024
This worked for me! Thanks!
corydeppen commentedon Oct 23, 2024
@drew-dulgar I'm running into the same as mentioned in #1917. I believe the
ColorSchemeScriptis necessary when using SSR since it's setting thedata-mantine-color-schemeattribute based on the scheme in local storage. I'm hopeful this can be resolved in Start so that scripts can be added to theheadwhen necessary in cases like this and not duplicated in the rootdiv.davidchalifoux commentedon Nov 21, 2024
I didn't realize the
?urlwas needed in the import, that fixed it for me. Thanks!schiller-manuel commentedon Mar 4, 2025
can this be closed?
icflorescu commentedon Mar 7, 2025
@schiller-manuel
Yes and no... Please keep in mind that Mantine applications are usually styled with CSS modules, so issues are still going to pop up until #3023 is fixed...
@kennyjwilli - remeber to also spread the
mantineHtmlPropson the<html>tag to avoid additional hydration errors:mapsgeek commentedon Apr 16, 2025
This setup for mantine with tanstack start, colorscheme without flashing or hydration errors
you need to setup a client side component for colorScheme toggler
and in app.config add this to vite
Tsouef commentedon Apr 26, 2025
I have the same issue. I tried all examples but still have the FOUC.
dperetti commentedon Sep 1, 2025
I was in the process of moving a small project from React Router (where everything runs fine) to Tanstack and I ran into this very quickly. Show stopper! 😟
ElasticBottle commentedon Sep 9, 2025
believe the same issue is happening when using next themes
Pyakz commentedon Oct 4, 2025
updates on React Router (Vite) + mantine?
0x0501 commentedon Nov 2, 2025
same issue here with NextUI and next-themes.
Spectral-Phoenix commentedon Jan 9, 2026
I am having the same issue, tried all the above fixes. nothing is working.
schiller-manuel commentedon Jan 10, 2026
@Spectral-Phoenix which issue do you have exactly?