Flash on initial load on the web

[florian-lefebvre]

What happened?

On the web I'd expect Uniwind to work with CSS variables ootb. Currently it seems it still needs some internal state.

I have an inline script that sets .light or .dark so it happens instantly. But the theme is not updated until Uniwind.setTheme() is called just a bit later, which causes a flash.

This pattern works in e.g. Astro when dealing with Tailwind so I assume some of the implementation here is not CSS only on the web. I know native have different constraints so this is just about web (+ a flash there does not occur on android).

Relevant files:

• https://github.com/florian-lefebvre/expo-starter/blob/fix/theme-flash/apps/app/src/app/%2Bhtml.tsx#L9-L19
• https://github.com/florian-lefebvre/expo-starter/blob/fix/theme-flash/apps/app/src/lib/theme-preference.ts#L26-L32
• https://github.com/florian-lefebvre/expo-starter/blob/fix/theme-flash/apps/app/src/app/_layout.tsx#L12-L15
• https://github.com/florian-lefebvre/expo-starter/blob/fix/theme-flash/apps/app/src/styles/global.css

Steps to Reproduce

1. Clone the code from the repository
2. From the root, run pnpm i --frozen-lockfile
3. From the root, run pnpm add web
4. Open the browser
5. In the top right, switch to dark mode (icon should be a moon)
6. Refresh the page

Things to observe:

1. If you open the element inspector, you can see the .dark class is applied immediatly on reload
2. You can see a flash, i.e. a delay until dark theme is actually applied

Snack or Repository Link

https://github.com/florian-lefebvre/expo-starter/tree/fix/theme-flash

Uniwind version

1.10.0

React Native Version

0.86.0

Platforms

Web

Expo

Yes

Additional information

• I've searched for similar issues in this repository and found none

[Brentlok]

Hey, thanks for the detailed report and reproduction.

The issue here is caused by useCSSVariable. This hook resolves a CSS variable to its current value, so on web it returns something like #ffffff rather than var(--color-background).

The resolved value is stored in React state and updates when Uniwind’s theme or variables change. Applying the .dark class directly updates the browser’s CSS immediately, but the hook needs to rerender.

The hook exists mainly for React Native libraries and components that cannot consume class names or CSS variables directly and instead require a resolved color value. For this use case, you can keep the CSS variable unresolved on web and only use useCSSVariable’s resolved value on native:

const useRealCSSVariable = (variable: string) => {
  if (Platform.OS === "web") {
    return `var(${variable})`;
  }

  return useCSSVariable(variable)?.toString();
};

This allows the browser to react to the .light or .dark class before React hydrates, while native platforms continue receiving the resolved value.

Screen.Recording.2026-07-17.at.10.43.58.mov

[florian-lefebvre]

That makes sense thanks! Applied a similar change and it fixes my initial report but now there's something else:

• I have my OS set to dark mode
• Using the theme switcher, I select light mode
• When I refresh, it starts as light (1) then flashes dark (2) then goes back to light (3)

The light class is applied ASAP by the inline script (step 1) so it's not the culprit. I also tried commenting out https://github.com/florian-lefebvre/expo-starter/blob/fix/theme-flash/apps/app/src/lib/theme-preference.ts#L27-L31 which removes step 3.

So to me it seems step 2 is not under my control, maybe a default behavior from Uniwind?

Btw thanks a lot for the help and the library, it's really great. I initially started with nativewind but so many issues...

[Brentlok]

The behavior comes from this code:

uniwind/packages/uniwind/src/components/web/rnw.ts

Lines 10 to 25 in 245f9af

	const addClassNameToRoot = () => {
	if (typeof document === 'undefined') {
	return
	}
	const root = document.documentElement
	;(Uniwind as unknown as UniwindWithThemes).themes.forEach(theme => root.classList.remove(theme))
	root.classList.add(Uniwind.currentTheme)
	}
	UniwindListener.subscribe(() => {
	addClassNameToRoot()
	}, [StyleDependency.Theme])
	addClassNameToRoot()

On line 24, Uniwind adds its current theme as a class on the root element.

At that point, your app is still using the initial system preference. If the system theme is dark, Uniwind.currentTheme is "dark", so Uniwind adds the dark class during initialization. Your stored preference is only applied later when restoreTheme() calls Uniwind.setTheme().

You could patch Uniwind to skip the initial addClassNameToRoot() call. However, that would temporarily leave the DOM theme and Uniwind’s internal theme state out of sync.

Ideally, the injected themeScript would also call Uniwind.setTheme(), but that script runs before the application bundle is initialized, so accessing the Uniwind instance from there would be difficult and likely impractical.

The other option is to patch Uniwind’s initialization behavior so that, on web, it derives the initial theme from the existing class on the root element instead of always starting from the system color scheme. That would allow the inline script to remain the source of truth for the first paint while keeping Uniwind’s internal state synchronized during initialization.

I don’t currently see a simple way to support this inside Uniwind without changing its initialization logic, but I’m open to suggestions.

[Brentlok]

Or if you don't need SSR at all you could just switch to SPA mode
app.json

"web": {
-	"output": "static",
+	"output": "single",
	"favicon": "./assets/images/favicon.png"
},

[florian-lefebvre]

I need SSR unfortunately. If you're open to that, I'd open a PR that wraps L24 so that it only runs if there's not a theme class already. Basically, assume the user handles it if already there

[Brentlok]

only runs if there's not a theme class already

This unfortunately won't work, because Uniwind.currentTheme will still be dark, so if you use useCSSVariable anywhere in the app it will flash initially, like whole page does now.

But I'm open for a change to check root class on initializing Uniwind, and fallback to color scheme if there's no theme class there

uniwind/packages/uniwind/src/core/config/config.common.ts

Line 17 in 245f9af

#currentTheme = this.colorScheme as ThemeName

Ideally it should be done in web specific config file because we don't want unused code shipped into mobile. Let me know if you have any questions

[Brentlok]

Release should land next week 🚀