StackBlur backgrounds

:warning: This is not supposed to be used as a theme by itself.

This is a theme component that’s supposed to handle the background only. It’s supposed to be incorporated into your theme design.

Repo: GitHub - hnb-ku/StackBlur-backgrounds-discourse-theme-component

This component uses Mario Klingemann’s StackBlur library (2kb gzipped - MIT license) to generate high scroll performance blurred backgrounds based on an image you select in a <canvas> element.

Examples: (these are compressed so they have artifacts - the backgrounds are smooth)

If I use this photo:

Then the resulting Discourse background would look like this:

And on mobile

More samples with other images:

The quality of the image you use does not really matter because the blur is very forgiving so I recommend highly compressed jpgs no larger than 1080p - All you want is the colors.


Install the repo as you would with any other theme component:

Once that’s done follow these steps:

1- Create a new theme
2- Name it whatever you want
3- Add this in the common header section:


4- Change BACKGROUND_URL_GOES HERE to the url of your image
(Has to be either hosted on your domain or on a domain with correct CORS set up)

5- Change BLUR_AMOUNT to the desired amount of blur (0 - 180) higher means more blur.

5- Add StackBlur backgrounds as a theme component under your newly created theme.

:warning: Important

The demo samples use the “Simple Dark” color scheme

You may have noticed the slight dark background behind the topic list.

This is not a part of the theme component

That is achieved with the the following CSS:

#main-outlet {
    background: rgba(0, 0, 0, .5);
    padding-left: 2em;
    padding-right: 2em;

Also, the default mobile theme adds a solid color background to the <body> element so you would need to remove that if you want the blurred background to show on mobiles. You can do that like so:

.mobile-view {
	body {
		background: none;


I’m using 1920x1080 image & no matter what theme I try using with this component, the image is being stretched. The blur appears to be working fine. Any thoughts on what could cause this?

Wouldn’t it be easier and faster to simply generate the blurred image and use that as the background? Why have the source JPG at all, plus an extra dependency…?

I guess if you are changing the background dynamically, that’s all I can think of?


I saw this in my logs today:



Everything works, so I’m not sure if this a reference error or warning of some kind. I just thought I would report it.

I tried to implement this but my forum components seem to turn completely transparent and it becomes incredible hard to read the text.


This is sadly still broken, @Johani perhaps if we are not supporting this long term we should just delete this topic ? Happy for you to fix it as well, up to you.


I’m using it on my site and everything seems fine. No problems here. However, I did modify the css a bit. I’ve been using this ever since I got Discourse.

1 Like