Introducing Discourse Splash - A visual preloader displayed while site assets load

Discourse is a single-page Javascript application.

This means that navigation within the app is blazingly fast. The compromise with modern web applications is that they must be loaded and parsed on the initial page view. While we’ve been doing a lot of work over the years to optimize how we serve site assets, this can sometimes be a little bit slow based on device/network conditions.

Over the last few weeks, we’ve been actively working and testing potential improvements for the initial wait that users on slow connections/devices encounter. We’re happy to announce that starting from this commit, Discourse sites will now display a splash screen while site assets load.

What does it look like?

We’ve had this enabled on Meta for a while, so you might have already seen it. If not, here’s what it looks like.

How does it work?

If a user loads your Discourse site, and Discourse isn’t parsed within the next two seconds, we show the splash. So, It’s based on connection time + 2 seconds.

We don’t display the splash for users on fast devices/connections.

How do I get it?

This is a feature in core, and the setting is default enabled now, so all you need to do is update to the latest. If, by some chance, you experimented with the setting we added and don’t see it, make sure that you have the splash_screen site setting enabled

What are the benefits?

On top of showing something to users on slow devices/connections. This feature also cuts down FCP/LCP delays on Discourse sites. We’ve built some internal tools to track FCP/LCP on Meta, and here’s what the results look like

Anything else I should know about?

The “loading” text that shows in the splash is based on the preloader_text translation string. Our community has been fantastic, and that text has already been translated into many languages. If you prefer it to be something different, you can customize that string under /admin/customize/site_texts?q=preloader_text on your site.

The splash screen does not delay your site in any way and only shows while the site assets load. Once the site is ready, the splash screen is immediately removed. There is no delay between the site being ready and removing the splash.


Would be interested to know if your internal data matches data that Google Search Console has on file for your CWV.


We use Google own Web-Vitals library for the internal metrics, so they will match. It’s just that info on the Search console has a wider feedback loop, so we captured those ourselves in order to iterate faster on the solution.

You can also verify the new LCP values using WebPageTest tool.


This looks great!

I know this may sound like a nerdy detail, but is it possible to change the colors of the circles on the loading thing? :grin:


For those who want to modify the loader, here’s the file:


The splash lives in a different CSS scope, so sadly, you won’t be able to modify the CSS via themes. That said, we do have planned improvements, and I started with this one.

Once the change is live on your site, the splash dots will use the colors from your current theme.


I think instead of that animation, the default Discourse spinner should be shown for consistency. Just an opinion though.

1 Like

Nice feature, have it now in latest upgrade.

I would have thought a priority before we worry about decor - would be for it to sync with dark theme, a sudden blast of full screen WHITE using the Dark theme, well is an insane attack on ones optical sensors when also in a dark room! :face_with_spiral_eyes:

Please at some :sunglasses: to keep consistency with dark theme.


My understanding is that we already sync the dark background @Johani ?

Trouble is that it can take a couple of seconds for the server to tell us we are dealing with a dark theme, we could improve second load with service worker wizardry, but it is a very very tricky problem


I noticed something since my last post, so to qualify - when logged out, I noticed discourse picks up the OS theme as dark, sets the discourse site as dark in tandem and thus the loading screen uses dark background color also to sync with theme-styling

However , when logged in as a user that is enabled dark theme as default, it reverts to white loading screen.

So I might be right in saying it s already 50% working as expected. :disguised_face:

I haven’t tested it out maybe someone else might give it a try.

1 Like

Yep, tested this today, this is how it’s behaving, works when logged out and then defaults to white screen when logged in as a user with DARK theme set, if you can make it behave same a when theme is detected for OS Dark theme, then that should be it.


Strangely enough, it seems to be based on whether my OS is set to light or dark mode, and Discourse does the opposite of what I’d expect. Basically, when set to dark mode Discourse flashes white, but when set to light mode, Discourse shows a dark page until content loads.

Here is dark mode. Note that it starts dark (iOS waiting to get data from the server), then flashes white (initial page load for Discourse I think), then loads the dark theme I have set:

And here is light mode. It starts white (iOS waiting to get data from the server), then turns dark (initial page load for Discourse I think), then stays in the dark theme I have set:


Interesting! Thanks for the Videos, @Johani will have a look and report back.


Yep that’s it, perfect example with video too!

I knew I wasn’t going mad! :crazy_face:


@Johani I updated the latest commit with what I assumed was the fix, or hopeful fix, but I am not sure it has made any difference (iOS, Safari / macOS Safari)

My connectivity is too good at the moment to replicate it easily, let me go find some dial up or something… :rofl:


On desktop, you can throttle your connexion using your browser’s dev tools: How to perform Network Throttling in Chrome | BrowserStack

I don’t know about mobile browsers though.


Thanks, I don’t use chrome but I’ll have a look at the xCode tools and configure some throttling.

I’ve had a bit more time and can confirm it remains the same.


This is possibly related to the white flashes, so I’m going to post it here.

iPhone in light mode, the top bar is dark. This is expected since it matches the dark Discourse layout I use.

iPhone in dark mode, the top bar is light. This is unexpected and like the white flash, seems to indicate that something about the layout is convincing the phone the page is white. The reason I say that is because Safari on iPhone tries to color the top bar to match the main color of the site you are viewing.


We did, but we missed the case where the user only sets the regular color scheme as dark. We previously relied on the OS preference to pick between the light/dark mode for the splash with the assumption that users set both and use the OS toggle.

I pushed a couple of fixes

If the regular scheme is dark, use that. If it’s light, use the light scheme for OS light mode and the dark scheme for OS dark mode (if it’s set)

The issue, as well as this one

should be fixed now. Thanks for the reports :+1:


:+1: Cool look forward to trying this out!

Suggestion - Branding

Is it possible to allow a basic logo customisation above the animated dots or to populated the “dots” with the logo (fav.ico size image) or a fixed low res fixed size (if load and speed is an issue).

Another user suggested returning the loading circle, which is a familiar artefact of discourse, which I think is a neat idea, for UI/UX consistency and would be enhanced by allowing specification of a base static site image/logo - it keeps the user oriented and located while in the limbo load state, increasing user experience and user confidence.

To add - grabbing the image form the existing branding setup, fav.ico or “logo small” is probably a good default.