Bug: Dark mode users see a white flash on page load

[rahul-rajak-nsut]

Summary

Dark mode users experience a white flash during initial page load because the theme is applied only after hydration completes.

Contexts

The current theme initialization runs after the page has already rendered once, causing the browser to briefly display light mode before switching to dark mode.

This behavior is noticeable during hard refreshes and slower page loads, especially when dark mode is stored in localStorage or inferred from system preferences.

Tasks

• Investigate the current theme initialization flow
• Ensure the correct theme is applied before first paint
• Verify dark mode persists correctly across refreshes
• Confirm no regression in light mode behavior

Acceptance Criteria

• No visible white flash during initial load in dark mode
• Works correctly with both saved preferences and system theme settings
• Existing functionality remains unaffected
• Tests/docs updated if required

Area

web

Difficulty

Easy to Intermediate — requires understanding of theme initialization and hydration timing.

[Soumika649]

Hi
I would like to work on this issue under GSSOC'26.
Could you please assign it to me?

[SaishWadnere]

I would like to work on this issue under GSSoC'26. The white flash occurs because the dark theme is applied after hydration, causing an initial light-mode render. I plan to fix this by adding a small inline script in the to apply the correct theme before the first paint and sync it with the existing theme logic.

I have reviewed the implementation approach and can submit a clean PR with testing and documentation updates. Please assign this issue to me if available.

[gungunpathak28]

Hi
I would like to work on this issue under GSSOC'26.
Could you please assign it to me?

[Anir2004-star]

Hey @rahul-rajak-nsut,
I'm Anirban, a GSSoC 2026 contributor. I'd love to work on this!
From what I can see, the white flash happens because the theme kicks in after hydration, so the browser briefly renders light mode first. My plan is to apply the theme earlier using an inline script before the first paint, and make sure it works consistently across refreshes without breaking light mode.
I've already set up the dev environment locally. Could you assign this to me?

Thanks!

[KaparthyReddy]

Hi @rahul-rajak-nsut, I would love to eliminate this initial page-load white flash for dark mode users by ensuring theme application occurs prior to the First Contentful Paint (FCP).

My Technical Implementation Plan:

Blocking Inline Script Injection: I will inject a lightweight, self-executing script (IIFE) directly inside the document (using Next.js theme-script logic or a blocking script tag with dangerouslySetInnerHTML). This script will synchronously read from localStorage and check window.matchMedia('(prefers-color-scheme: dark)') to immediately append the .dark class to the element before the body markup parses.

Preventing Next.js Hydration Mismatch: To ensure React doesn't throw a layout mismatch error when it pairs the server-rendered HTML with the newly class-modified client DOM, I'll align the client-side state initialization inside a useEffect hook to smoothly capture the pre-applied class without triggering a re-render loop.

Robust System Changes Listener: I will wire up an event listener to dynamically track change events on system preference overrides so that if a user changes their OS theme mid-session, the UI synchronizes perfectly without requiring a hard refresh.

I have my local environment ready, understand hydration mechanics, and can ship a clean, test-backed fix today. Please assign this to me!
/assign gssoc26

[rahul-rajak-nsut]

@KaparthyReddy @Anir2004-star
Hey guys, I’m also a contributor here. This issue was raised by me, but I’m not the project owner or maintainer, so I can’t assign it to anyone.

For now, I’m also waiting for this issue to be assigned to me by the maintainers.

Sorry for the confusion.

[ShantKhatri]

@SaishWadnere @KaparthyReddy @Anir2004-star @rahul-rajak-nsut @gungunpathak28 Could you all guys please help here to review this(#61 ) PR. We are totally open to close that big PR too, if that is not aligning with the reference doc we have.
As it's dependecy to start with this issue.

I'm happy to assign issues personally to all you guys, by understanding your requirements. As we have 200 planned issues to open too.

[KaparthyReddy]

Hey @ShantKhatri, I've reviewed PR #61 locally by checking out the branch
and running the dev server. Left my feedback there. Looking forward to
working on the dark mode flash fix once the dependency is resolved!

[Anir2004-star]

"Hey @ShantKhatri, thanks for the tag!
I'm ready to work on #91 once PR #61
is resolved. Could you assign me to
any other available issue meanwhile?"

[vaanni47]

I’ll be eliminating the "white flash" experienced by dark mode users by optimizing our theme initialization flow to trigger before the first paint. My approach involves moving the theme detection logic—whether it's from localStorage or system preferences—into a blocking script in the of our document, ensuring the correct styles are applied before hydration even begins.

i'd like you to assign this to me please

[Midoriya-w]

Hey @ShantKhatri! I'm a GSSoC 2026 contributor and I've been actively contributing to other projects in the program. I'd love to work on DevCard especially the DevOps/infrastructure side.
I'm particularly interested in:

#45 CI pipeline with GitHub Actions
#37 Docker Compose setup

I have hands-on experience with both from my recent GSSoC contributions. Could you assign one of these to me? Happy to start immediately!

[anuragbraveboy-sudo]

Hey @ShantKhatri! 👋

I'd love to work on this issue under GSSoC'26!

Root Cause I've Identified:
The white flash happens because the browser renders the page before JavaScript loads — so the dark class is applied too late. This is a classic FOUC (Flash of Unstyled Content) problem.

My Fix:

• Add an inline <script> inside <svelte:head> in +layout.svelte that reads localStorage and applies the dark class before the page renders
• This runs synchronously, so no flash will occur
• No external dependencies needed

Why this approach:

• It's the industry-standard solution used by major sites (Next.js, SvelteKit docs, etc.)
• Minimal code change — no redesign needed
• Works across all browsers

I've already contributed to this repo (PR #182) so I'm familiar with the codebase. Ready to start immediately! 🙏

[Harxhit]

@KaparthyReddy I have assigned this issue to you.