Beginner's guide to using Discourse themes


(Joe) #1

This is a crash course in Discourse theme basics. The target audience is everyone who is not familiar with Discourse themes. If you’ve already used Discourse theme / theme components, this guide is probably not something you need to read.

This guide is broken into the following sections.

(You can click on any of the following sections to jump to it)

What are themes and theme components?

A theme or theme component is a set of files packaged together designed to either modify Discourse visually or to add new features.

Let’s start with themes.


In general, themes are not supposed to be compatible with each other because they are essentially different standalone designs. Think of themes like skins, or like launchers on Android. You can have multiple launchers installed but you can't use two of them at the same time. Your default Discourse installation comes with two themes


and Dark

Let’s say that’s not enough for you and you want MOAR. Well, you can install additional themes fairly easily. Here are a couple of examples of free themes available here on Meta.

Material Design Theme

Sam’s personal “minimal” topic list design


As you can see, your site can look dramatically different based on what theme you select; however, that’s not the end of it. On top of themes, Discourse also supports theme components.

Theme Components

We use the phrase theme-component to describe packages that are more geared towards customising one aspect of Discourse. Because of their narrowed focus, theme components are almost always compatible with each other. This means that you can have multiple theme components running at the same time under any theme. You can think of theme components like apps on your phone.

As always, examples are the best way to describe something, so here are a few examples of theme components available here on Meta

Discourse Category Banners

This theme component takes your existing category details, including name, description, and color and generates a banner at the top of the relevant category pages.

Brand header theme component

This theme component adds an extra top header for branding with your logo, navigation links, and social icons for both mobile and desktop views. Brand logo can be a image or text.

Tiles Image Gallery

A lightweight theme component that adds image gallery functionality to Discourse posts.

As you can see, theme components have a much narrower focus. As such, they are compatible with each other in most cases.

Now you have a general idea of what Discourse themes and theme components are. Let’s dig a little deeper.

Discourse Theme Interface

Let’s look at the interface for themes. Go to and you should see something like this:

This is the default theme interface in Discourse. You can do a number of things here:

  • Set the default active theme
  • Choose which themes to make available to your users
  • Create new themes and theme components
  • Import new themes and theme components
  • Add theme components to a theme
  • Modify color schemes
  • Change theme settings
  • Preview a theme

Let’s go through these one by one.

Set the default active theme

The small asterisk next to the default theme name indicates that this is the active theme on your site.

Now let’s change the active theme to Dark. Click on the Dark theme and you should see this:

If you click on the check box here

The active theme on your site will be set to Dark. This means that everyone who visits your site will see this:

And the asterisk would then move to be next to the Dark theme name indicating that it is the active theme

Choose which themes to make available to your users

It’s nice to be able to set a theme for your site, but you know what’s nicer? Letting your users decide. Discourse allows you to offer different themes to your users allowing them to set the theme according to their preferences. Their choice is limited to their own account and won’t affect your active theme choice or the choices of the other users.

For example, you can set the active theme to the default theme (light) but offer the dark theme as a option. Let’s try and do that now. In the theme interface, you can see a small “user” icon next to the default theme name. This icon indicates that the theme can be selected by users.

If you want to make the Dark theme user-selectable, click on it and then enable this option:

The same “user” icon will now show up next to the Dark theme name indicating that it’s user-selectable

and your users will be able to select whatever theme they prefer by going to

Create new themes and theme components

To create a new theme or theme component you click here

You would then be able to

  1. Change the name of the theme / theme component
  2. Set or change a color scheme for the theme
  3. Add html / css / js to theme / theme component
  4. Add files or uploads to the theme

Specific customisations are outside of the scope of this guide and so I’ll stop here for this point.

The interface for adding html / css / js looks like this (once you click on #3 above)

Import new themes and theme components

We already have a guide for how to import themes, but I’m including how to do that in here since this guide is supposed to cover all the basics.

If you click on import here

you’ll see this

You can then import theme files from your device or via a the theme repository link. The repository link for each theme is provided by the author on the theme topic. Once you import a theme, all the things we discussed earlier will apply to it. You can set it as default, make it user-selectable and so on.

Add theme components to a theme

Let’s say you like the Discourse category banners theme component and want to use it. You would proceed as follows

  • import the theme from the repository like we discussed below
  • add it as a theme component to your active / user-selectable themes

You can do that like so:

After importing the component, go to the theme you want to add it to and look for the Theme components section

This list will show all installed theme components. From there you can add theme components to the theme. If we add the Discourse category banners theme component it would look like so

That’s pretty much it. Discourse category banners is now an active component of the default theme. If you also want it to be added to the Dark theme, you would repeat the process of adding the theme component for the Dark theme.

If you’ve set the Dark theme to user-selectable and added the Discourse category banners theme component to it as well, users who select the Dark theme as their active theme will also get the Discourse category banners theme component as well since it’s a “child-theme” of the Dark theme.

You can have an unlimited number of theme components under a theme and like we discussed earlier, they’re usually compatible with each other. So you can do something like this:

And all those components would be active on the default theme at the same time.

Modify color schemes

A color scheme is a palette of colors that you choose to generate the color of the elements in a theme. I won’t go into a lot of details here but will show you how to use color schemes.

Navigate to and you will see

From here you can edit color schemes or create new ones. To edit a color scheme, click on it and change the colors to your liking

To create a new color scheme click here

Once you’re done changing the colors, it’s now time to set the color scheme as active in either your active or user-selectable themes. To do so, go to the theme’s page and look here

Theme settings

Discourse themes can have settings. These settings are designed to be an easy way for you to configure a theme or theme component according to your needs. For example the Discourse Button Styles theme has a few settings to allow for easy customisation of how buttons look by simply changing a few values to your liking

Not all themes / theme components have settings but for those that do, they will always show up here. Settings will usually include instructions provided by author that help you determine what changes need to be made.

Previewing a theme

Sometimes you need to see what a theme looks like on your site before applying it. Discourse offers an easy way to preview themes without setting them as active.

While on a theme’s page, click here

and a new tab will open with a live preview of what the theme would look like on your site. You can navigate to different pages and see how everything looks like

Additional information


Discourse has a built-in way to bypass the current active theme in case things go wrong. For example, a javascript error in a component’s code may cause your site to not work properly. To bypass the current active theme simply visit

You would then see

from there you can disable the current active theme, navigate to the theme page and either fix the problem or disable the theme for good.

Getting new themes

The most straightforward way to find new themes and theme components is to check the #theme category here on Meta.

Further reading

Developer’s guide to Discourse Themes
How to use Discourse Safe Mode
How to develop custom themes
Create and share a font theme component
How to create and share a color scheme
How to use Discourse core variables in your theme
How to add settings to your Discourse theme
Theme Creator, create and show themes without installing Discourse!

If you have any questions, don’t hesitate to ask.

This guide is a wiki, so if you see something wrong, feel free to fix it.

Developer’s guide to Discourse Themes
How to add whatsapp in the share button list next to facebook
Incorporating Amazon OneLink: making affiliated links on global forums much easier
Force Mobile Homepage
Easy responsive footer
Different landing page for desktop vs mobile theme?
Filter topic with specific tag inside single category
Any options for over-riding the username restrictions?
Theme Creator Web Dev Help
Header submenus
Changes on the handlebar templates not reflecting on the browser
Configure tag color
Whitelisting some HTML tags
Custom Header Links
How to add whatsapp in the share button list next to facebook
How to enable Matomo analytics on Discourse
(Erlend Sogge Heggen) #2

3 posts were split to a new topic: Looking for theme gurus