Beginner's guide to using Discourse Themes

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.

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 check mark 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:

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

And the check mark 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 an option. Let’s try and do that now. In the theme interface.

All active themes you have, whether it’s the default theme set on your site or any themes you’ve marked as user-selectable will show here:

However only the default theme will have the green check mark.

Now, let’s try to make the Red theme user-selectable for example.

All you need to do is click on it, and then tick the box that says “Theme can be selected by users”

That’s it! You’ll notice that it automatically gets moved from the inactive theme list to the active theme list

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, click either of the two “Install” buttons

You’ll then get dialog box. Select the “Create new” option on the lefthand menu. You will need to provide a name for what you want to create and decide whether it’s a theme or theme component.

We’ve sort of covered the basics of what themes and theme components are. If you remember, a theme-component is usually focused on modifying one area of Discourse. Whereas a theme generally covers a number of things. You should also note that a theme can have any number of theme components under it, while a theme-component cannot. Don’t stress about this for now, a more detailed explanation of this relationship will follow later.

Now, let’s say you’ve decided on the name and decided to make it a theme. Well, once you hit the “Create” button, the theme will be created and 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
  5. Add child components to your 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.

To import a theme or theme component, click either of the two “Install” buttons

The “Popular” section will allow you to preview/install from a list of our most popular themes and components.

You can also 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.

If you import a theme component, you can also add it to any of your themes. This is covered in detail in the next section

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

  1. import the theme from the repository like we discussed above
  2. 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 “Included components” section

This list will show all installed theme components. From there you can add theme components to the theme. Adding the Versatile Banner theme component would look like so

A similar, “Include component on these themes” option exists from an individual component’s page. This allows you to add a component to multiple themes at once

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

the best part about previewing a theme is you can test out changes live without causing any problems on your site in case anything goes wrong.

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

Designer's Guide to Discourse Themes
Developer’s guide to Discourse Themes
How to enable Safe Mode to troubleshoot issues with themes and plugins
Structure of themes and theme components
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.

DiscoTOC - automatic table of contents
Header Submenus
Force Mobile Homepage
Easy Responsive Footer
Changes on the handlebar templates not reflecting on the browser
(+ New topic) button on all pages
Where do I edit topic list colors?
Local image ad banners?
Omit Emoji component
☁️ Discourse Air Theme
Como faço para entender esse fórum? (How do I understand this forum?)
Full name @mentions
Best Workflow for Maintaining Themes?
☁️ Discourse Air Theme
How to create a theme (if I am a pure end user)
Linkify words in post
Discourse Popular Tag Sidebar
Place for total coding beginners to learn how to customise?
Can I install an external application from github running on discourse
Newbie help accessing code
Per-category Terms of Service
DiscoTOC - automatic table of contents
Private Message Can't Be Reached with private messaging disabled
DiscoTOC - automatic table of contents
Categories Layout Override
Return to start of topic
:cherry_blossom: Discourse Sublime Theme
Group specific tool bar
Theme Stelpolva: A discourse rounded theme based on Default Theme
Custom Hamburger Menu Links
Discourse Category Sidebars
Desktop to Mobile View Banner
Link from inside the topic to itself
Custom user menu tab
Discourse Tag Sidebars
Moonclaw Theme port
Discourse Tag Cloud
Featured Flip Cards
Main banner doesn't appear when theme was changed
Codeblock Theme Picker
Theme-Component v Plugin: What's the difference
Can I turn off location?
Blog Post Styling
Extended About Page
Category Hider Theme Component
Category Previews
Wide image extending until search icon?
Expanded Create Topic Component
How to add Google Custom Search Engine to Discourse
DiscoTOC - automatic table of contents
Inline PDF Previews
How do I add category banners?
FKB Pro - Social theme
What's the fastest and easiest way to add a persistent javascript file or snippet
Banner opacity and disabling profile pictures / avatars
Wordpress in header, Discourse in footer ? Both sticky
Topic List Previews (legacy)
Add Text In Header Beside Logo
How to remove borders in tables?
Custom header colour and category icons and login button
Discourse Web Page Watermark
Removing all categories (or just "uncategorized") from hamburger menu
Hide Likes For New Users
Hide an Authentication Method from the UI
How to remove the number of months in the category section
Styling front page category title & nav container background
Category descriptions not showing up on mobile
How customize the appearance of sections like Amazon?
Selectively hiding numbers
Install a new language for Highlight.JS on a hosted discourse
Homepage (sub)category display - lots of whitespace
How to update Theme Components when running on Ubuntu
Javascript code snippet injection for cookie tracking
🎀 Neomorphism, a modern theme for Discourse
Dracula a Dark Theme for Discourse
OrgChart component
How can I add a menu item
Adding statcounter code
Grogu, a theme inspired by "The Mandalorian"
Versatile Banner
Left side hamburger menu on mobile
MD Composer extras
Video Upload to YouTube and Vimeo using Theme Component
How to add a simple Banner
Custom Top Navigation Links
Personal Message Bubbles
Custom Header Links (icons)
Discourse for self hosting
Mint, a modern theme for Discourse :herb:
☁️ Discourse Air Theme
Make "New Topic" button more prominent
How can I add a analytics script into the header of my community?
Display replies and likes count in mobile view
Help needed with theming and logo
Wikified Posts Component
Discourse Coloring Tag
🖋 Inky, a theme to make reading easy
Welcome Link Banner
MD Topic List component
MD Topic List Mobile component
HTML tags showing in banner and don't know where to change it
:classical_building: Rome, a theme inspired by ancient roman manuscripts
How to add a script at the beginning of page header?
Recommendations on layouts? A way to preview changes?
Is it possible to change Topic Title prompt for a category?
Need a plugin coded to allow certain css codings in forum
Timeline bookmark button
Category Icons
Discourse hamburger tags
IFrame Lightboxes
Changing theme color for the forum
Change Excerpt of topic to go to latest post instead of that specific message
How do I test drive UI changes?
How do I test drive UI changes?
Discourse svgbob
Colored Tag Styles
Group Categories Page Override
Voice Recorder Component
Discourse Show Fullname in Mentions
Header Locale Selector
Top Contributors Sidebar
Homepage Feature
Custom Homepage
Customized Inline Codeblocks
User Portfolio
Category Banners
Matomo Analytics
Colorful Categories
Net Promoter, Satisfaction scoring?
What is the name of this theme?
DiscoTOC - automatic table of contents
Social Share
Discourse Gifs
Kanban Board
Topic List Excerpts
Unanswered Filter
Discourse Solved Quote Customization
Post Badges
DiscoTOC - automatic table of contents
DiscoTOC - automatic table of contents
Featured Tiles
Reply Template
Trendy Login
Topic Author
Placeholder Forms
Search Banner
Jitsi Video Conference
Brand Header
Show Original Poster Avatars
Categories Tag Column
PM Dropdown Button
Timeline with labelled step by step sections - how is this achieved?
User Card Directory
Tag Icons
Tag Banners
Guest Gate Theme Component
Offline Indicator Theme Component
Showcased Categories
Sidebar Tags
Signup Banner
Submit from Preview (Mobile)
Insert Video
Hamburger Theme Selector
Google Fonts
Hide Muted Categories
Category Groups
Categories Tracking Toggle
Gated Topics in Category
Halloween Decorations :ghost:
User Field Prompt
Whereby Video Meetings
Sticky Avatars for Mobile
Change the Like Icon to :+1:
Right Sidebar Blocks
DarkPixlz's Modern Theme
Custom Lightbox
About the theme category
Sticky New Topic Banner
Clickable Topic
Header Search
Topic Count in Category Boxes
Group Timezones
Remove Name Suppression on Posts
Warning banner for old Android devices affected by Let's Encrypt changes
Fakebook, a theme for social media lovers
CSS Classes for Current User's Groups
Compact Nav
Dice Roller
Baidu Search
A Graceful theme for Discourse
Zeronoise. A theme aiming to create a pleasant reading experience
Avatar Size and Shape
Discourse Icon
Topic Status Filter
GitHub Status Indicators
Minima, a minimal theme for Discourse
Topic Footer Buttons
Thin Header
Sam's Simple Theme
Optional Mobile Title Header
Custom Code
Intercom Widget
Discourse Mermaid
Ghost, a cyberpunk theme for Discourse
Custom Category Boxes
🌺 Hibiscus - Springtime Discourse theme
Discourse Classic Theme
About the theme-component category
Topic List Thumbnails
Unformatted Code Detector
Dark/Light Mode Toggle
Fakebook, a theme for social media lovers
Discourse Docs Card Filter
Add a custom header with a dropdown menu
How to add whatsapp in the share button list next to facebook
Designer's Guide to getting started with themes in Discourse
(Obsolete) Use Amazon OneLink to make affiliated links on global forums much easier
Create a banner to display at the top of your site
Sidebar theme toggle
Blackout - A Theme For OLED Displays
Issues adding CSS/JS component: Robustifying links to preserve link functionality
Horizontal loading slider
Composer Footnote Button
Account Deletion Request
:toolbox: Developer Toolbox
Desktop PWA Navigation
Lightweight Topic List Container
Table Builder
Customize the header with links, icons, or menus
Beginner's guide to developing Discourse Themes
Install a theme or theme component
Disable Likes
Buttons for Scrolling to the Top/Bottom of Topics
Make CSS changes on Your Site
Floating Navigation Controls and Desktop Navigation Bar for Mobile
DiscourseConnect Signup Button
Alien Night Theme - A free Dark Theme for Discourse
🌐 www theme
Integrate Appzi feedback tool to front-end of discourse
Header Categories Navbar
Report Content to Group
Open In Script Editor
Hide sidebar from anon users
Share Link Shortener
Pinboard, a simple UI theme
Contributing to Discourse
Adding images to image tag inside header
Mobile Category List Adjustments
House Ad Templates
Red-light theme
Scroll to Top Component
Is it possible to edit plugin components?
Embed whole forum
Land on Group Messages Component
Adding images to image tag inside header
Theme Developer Quick Reference Guide
Require Edit Reason
Made some changes I cannot revert
Custom Header Links
Applying a custom header to Discourse site
Blog Post Styling
Which is Better? Discourse or Flarum?
What is the purpose of the "Convert" button with themes?
How can i set topic image' width
Scrollable Post Content
Custom Header Links
Hide Users Column
Where can i get discourse themes?
Discourse-webpack: A boilerplate for developing JS-heavy Discourse components
Where to place ad script?
How to make your side have a side-bar and external links
Hide full name if not logged in
Add Likes Column
Override icon / color
Restrict uploads
Application Files after Digital Ocean Setup
Beginner's guide to developing Discourse Themes
Get started with Theme Creator and the Theme CLI
Install a theme or theme component
Changing layout with themes
Image not filling header container
Configure tag color
Custom Header Links
Is anyone working on a Discourse Wiki?
Trust-Level Avatar Flair
How to add whatsapp in the share button list next to facebook
Floating "New topic" button
Floating "New topic" button
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
Status Page (Atlassian)
Whitelist, allowed iframe
Is it possible to create child themes?
Youtube embed size, revisited
Easy Responsive Footer
How to change paragraph font size?
Compliant Google Login Button
Add Category Column
Auto-Hide Post Editor Preview
Discourse Coloured Text
Alternative Voting Category Style
Discourse Cookie Consent Banner
Raw Post Button

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

2 posts were split to a new topic: Need help adding header links and image slideshow to my site

I recently followed this guide (thank you!) and successfully installed several theme components on my site. I later found out that one of them was broken and that there was a #theme:broken-theme category. This would have been good to have in the guide, but I can’t edit it, but I suggest someone add this information above. Thanks!


Theme components seems to be user preferences.
Say I have 3 theme components, if I’d like to allow users to choose which components to turn on, do I have to create 2^3=8 themes to support that? Is there a feature request to make theme components to switch off on a per-user basis?

Yes @tgxworld is looking to build an on/off option for components per user, probably should be done in a week or so.


On many places, it is written, just add this code to CSS.
Then I tried that code/functionality to Admin Settings> Customize> Themes> Edit CSS/HTML. And paste the given code under ‘CSS’ or last pane ‘Embedded CSS’.
But there is no result.

Is there any guide which could tell the basics of how css/html code is pasted and in which area (there are many other panes/tabs also: ; Header ; After Header ; ; Footer )


Was this ever published? Or was it made possible to add a user preference in just a theme component rather than a plugin?


As per the guide, I should be able to see two default themes.

But in my case I’m able to see only default and not even Light or Dark theme.

Also the dark theme should be able to change as per the browser/system dark/light mode. This isn’t happening too.

Can anyone please help me to fix it?


If your Discourse is a bit old you won’t have the two default themes, but you can easily create one with preset dark color palette. It takes a few seconds.


Hello Steven, thanks for your reply.

I’m running the 2.7.0.beta1 version of Discourse.

1 Like

I have manually created 2 themes light and dark and assigned palettes to them and I think that is the only option left for me.

1 Like

I don’t think you have another option. What I meant by “old forum” was more like if it was created more than 2 or 3 years ago. The two themes by default was added fairly recently I believe, half the forums I installed don’t have these two themes, they have the same “Default” as you.

But theese two default themes have nothing more than those you just created


Sorry I’m new using discors i try to install a theme component the “discourse-category-banners”
but it’s doesn’t seems to works they ask me :

i didn’t understands how to make it work

1 Like

The warning that you are seeing is telling you that you cannot make changes to the theme component’s code directly on the Discourse site. The warning is shown because it used to be possible to edit this type of theme component directly on Discourse. That caused all sorts of issues.

To use the theme component, all you need to do is add it to your theme. I see in the screenshot that you posted that you have added the theme component to your site’s default theme. As long as your user is using the site’s Default theme, you should see category banners on the site.

Use the Discourse Category Banners Themes Settings section to configure the component for your site.


Is there any actual documentation or is all of your API info buried in threads?

1 Like

Is this any help?


See also


A post was split to a new topic: Why is my theme dark?