# Beginner's guide to using Discourse Themes
**URL:** https://meta.discourse.org/t/beginners-guide-to-using-discourse-themes/91966
**Category:** Site Management
**Tags:** reference, customization
**Created:** [July 10, 2018, 12:10pm UTC](https://meta.discourse.org/t/beginners-guide-to-using-discourse-themes/91966 "2018-07-10T12:10:56Z")
**Posts on this page:** 15
**Page:** 1
### Author:  [@Discourse](https://meta.discourse.org/u/Discourse)
#### Post date: [July 10, 2018, 12:10pm UTC](https://meta.discourse.org/t/beginners-guide-to-using-discourse-themes/91966/1 "2018-07-10T12:10:56Z")
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.
#### 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: **Foundation** and **Horizon**.
Foundation is a clean, classic Discourse look, while Horizon offers a more modern design with multiple color palettes to choose from (such as Horizon, Royal, Clover, Lily, Violet, and Marigold — each with light and dark variants).
Foundation
and [Horizon](https://meta.discourse.org/t/horizon-theme/360486)
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](https://meta.discourse.org/t/material-design-stock-theme/47142)
[Sam’s personal “minimal” topic list design](https://meta.discourse.org/t/sams-personal-minimal-topic-list-design/23552)
[Mint](https://meta.discourse.org/t/mint-theme/202822)
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](https://meta.discourse.org/t/discourse-category-banners/86241)
> 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](https://meta.discourse.org/t/brand-header-theme-component/77977)
> 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.
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 `your.site.com/admin/customize/themes` 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 palettes
- Change theme settings
- Preview a theme
Let’s go through these one by one.
#### Set the default active theme
You can see a badge indicating that a theme is set as the default:
Now let’s change the active theme to Horizon. You can do this from the menu button … or by clicking the theme’s name and selecting the checkbox on the settings page:
The active theme on your site will be set to Horizon. This means that everyone who visits your site will see this:
#### 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 (Horizon) but offer the Foundation theme as an option. Let’s try and do that now in the theme interface.
All you need to do is click on the menu button …, and then select “Allow users to select”
That’s it! it will now get a “user selectable” badge
and your users will be able to select whatever theme they prefer by going to
`your.site.com/my/preferences/interface`
#### Create new themes and theme components
To create a new theme or theme component, click the “Install” button
You’ll then get dialog box. Select the “Create new” option on the 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 palette for the theme
3. Add child components to your theme
4. Add html / css / js to theme / theme component
5. 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 #4 above)
#### Import new themes and theme components
We already have [a guide for how to import themes](https://meta.discourse.org/t/installing-a-theme-or-theme-component/63682), 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, the “Install” button
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 Homepage Feature 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. Homepage Feature is now an active component of the default theme. If you also want it to be added to another theme, you would repeat the process of adding the theme component.
If you’ve set the Foundation theme to user-selectable and added the Homepage Feature theme component to it as well, users who select the Foundation theme as their active theme will also get the Homepage Feature theme component as well since it’s a “child-theme” of the Foundation 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 theme at the same time.
#### Modify color palettes
A color palette is a set 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 palettes.
Navigate to `your.site.com/admin/config/colors` and you will see
From here you can edit color palettes or create new ones. To edit a color palette, click on it and change the colors to your liking
To create a new color palette click here
Once you’re done changing the colors, it’s now time to set the color palette 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 Homepage Feature theme component has a few settings to allow control of which topics are featured:
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 what 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
##### Safe-mode
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
`your.site.com/safe-mode`
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 #Customization > Theme and #Customization > Theme component category here on Meta.
#### Further reading
[Designer's Guide to getting started with themes in Discourse](https://meta.discourse.org/t/designers-guide-to-discourse-themes/152002)
[Developing Discourse Themes & Theme Components](https://meta.discourse.org/t/developer-s-guide-to-discourse-themes/93648)
[Using Safe Mode to troubleshoot issues with themes and plugins](https://meta.discourse.org/t/how-to-use-discourse-safe-mode/53504)
[Structure of themes and theme components](https://meta.discourse.org/t/structure-of-themes-and-theme-components/60848)
[Create and share a font theme component](https://meta.discourse.org/t/create-and-share-a-font-theme-component/62462)
[Create and share a color scheme](https://meta.discourse.org/t/how-to-create-and-share-a-color-scheme/61196)
[Use Discourse Core Variables in your Theme](https://meta.discourse.org/t/use-discourse-core-variables-in-your-theme/77551)
[Add settings to your Discourse theme](https://meta.discourse.org/t/how-to-add-settings-to-your-discourse-theme/82557)
[Theme Creator, create and show themes without installing Discourse!](https://meta.discourse.org/t/theme-creator-create-and-show-themes-without-installing-discourse/84942)
If you have any questions, don’t hesitate to ask.
> Last edited by @Moin 2026-07-09T16:31:30Z
>
> > **Check document**
> >
> > Perform check on document:
---
### Author:  [@erlend\_sh](https://meta.discourse.org/u/erlend_sh)
#### Post date: [July 16, 2018, 7:55am UTC](https://meta.discourse.org/t/beginners-guide-to-using-discourse-themes/91966/2 "2018-07-16T07:55:59Z")
3 posts were split to a new topic: [Looking for theme gurus](https://meta.discourse.org/t/looking-for-theme-gurus/92437)
---
### Author:  [@jomaxro](https://meta.discourse.org/u/jomaxro)
#### Post date: [January 3, 2019, 7:02pm UTC](https://meta.discourse.org/t/beginners-guide-to-using-discourse-themes/91966/3 "2019-01-03T19:02:07Z")
2 posts were split to a new topic: [Need help adding header links and image slideshow to my site](https://meta.discourse.org/t/need-help-adding-header-links-and-image-slideshow-to-my-site/105624)
---
### Author:  [@rhyolight](https://meta.discourse.org/u/rhyolight)
#### Post date: [February 19, 2019, 5:35pm UTC](https://meta.discourse.org/t/beginners-guide-to-using-discourse-themes/91966/4 "2019-02-19T17:35:44Z")
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](https://meta.discourse.org/t/add-users-to-top-nav/63681/25) and that there was a #customization: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!
---
### Author:  [@BobbyZopfan](https://meta.discourse.org/u/BobbyZopfan)
#### Post date: [May 24, 2019, 1:59pm UTC](https://meta.discourse.org/t/beginners-guide-to-using-discourse-themes/91966/16 "2019-05-24T13:59:56Z")
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 )
---
### Author:  [@scottyweeks](https://meta.discourse.org/u/scottyweeks)
#### Post date: [June 13, 2022, 1:26pm UTC](https://meta.discourse.org/t/beginners-guide-to-using-discourse-themes/91966/33 "2022-06-13T13:26:36Z")
Is there any actual documentation or is all of your API info buried in threads?
---
### Author:  [@JammyDodger](https://meta.discourse.org/u/JammyDodger)
#### Post date: [June 13, 2022, 1:32pm UTC](https://meta.discourse.org/t/beginners-guide-to-using-discourse-themes/91966/34 "2022-06-13T13:32:53Z")
Is this any help?
> [@Reverse engineer the Discourse API](https://meta.discourse.org/t/how-to-reverse-engineer-the-discourse-api/20576):
>
> Discourse is backed by a complete JSON api. Anything you can do on the site you can also do using the JSON api. The API is documented at [docs.discourse.org](https://docs.discourse.org). You can also use the [discourse\_api](https://github.com/discourse/discourse_api) Ruby gem as a client library. However, not every endpoint is documented. To determine how to do something with the JSON API here are some steps you can follow. Example: recategorize a topic. Go to a topic and start editing a category: Open Chrome dev tools, switch to the Network tab, select …
---
### Author:  [@pfaffman](https://meta.discourse.org/u/pfaffman)
#### Post date: [June 13, 2022, 2:21pm UTC](https://meta.discourse.org/t/beginners-guide-to-using-discourse-themes/91966/35 "2022-06-13T14:21:26Z")
See also [https://docs.discourse.org/](https://docs.discourse.org/)
---
### Author:  [@Diego\_Santos](https://meta.discourse.org/u/Diego_Santos)
#### Post date: [April 21, 2024, 1:02am UTC](https://meta.discourse.org/t/beginners-guide-to-using-discourse-themes/91966/43 "2024-04-21T01:02:09Z")
Hello,
I don’t see the option “Admin Settings\> Customize\> Themes\> Edit CSS/HTML” available. What should I do to enable this button?
---
### Author:  [@Moin](https://meta.discourse.org/u/Moin)
#### Post date: [April 21, 2024, 1:24am UTC](https://meta.discourse.org/t/beginners-guide-to-using-discourse-themes/91966/44 "2024-04-21T01:24:00Z")
You can use a new theme component
> [@Open the login popup Or trigger event when button is pressed](https://meta.discourse.org/t/open-the-login-popup-or-trigger-event-when-button-is-pressed/136385/7):
>
> You can create a new Theme component and attach it to your theme.
>
> - Go to Admin → Customize
> - Click on Install button
> 
> - Then attach it to your theme and click on Edit CSS/HTML button
> 
---
### Author:  [@Eric\_Wynn](https://meta.discourse.org/u/Eric_Wynn)
#### Post date: [March 26, 2025, 11:30am UTC](https://meta.discourse.org/t/beginners-guide-to-using-discourse-themes/91966/49 "2025-03-26T11:30:10Z")
Probably a silly question here.. But can you give each category its own “Theme”?
Thanks in advance
---
### Author:  [@Arkshine](https://meta.discourse.org/u/Arkshine)
#### Post date: [March 26, 2025, 9:55pm UTC](https://meta.discourse.org/t/beginners-guide-to-using-discourse-themes/91966/50 "2025-03-26T21:55:06Z")
Hi Eric, welcome!
There are no silly questions! While there is no built-in feature to achieve that, you can assign each category a unique style by using category-specific [CSS](https://meta.discourse.org/t/making-custom-css-changes-on-your-site/168101) with a [theme component](https://meta.discourse.org/t/customizing-your-site-with-existing-theme-components/312297?silent=true), for example.
---
### Author:  [@Weronika\_Ostrowicka](https://meta.discourse.org/u/Weronika_Ostrowicka)
#### Post date: [July 9, 2026, 2:48am UTC](https://meta.discourse.org/t/beginners-guide-to-using-discourse-themes/91966/52 "2026-07-09T02:48:05Z")
Is there any updated version? My whole UI looks different and I am struggling to find my way around…
---
### Author:  [@NateDhaliwal](https://meta.discourse.org/u/NateDhaliwal)
#### Post date: [July 9, 2026, 11:04am UTC](https://meta.discourse.org/t/beginners-guide-to-using-discourse-themes/91966/53 "2026-07-09T11:04:09Z")
Hi there! Which parts do you need help with? Are you an admin or a regular user? Thanks.
---
### Author:  [@awesomerobot](https://meta.discourse.org/u/awesomerobot)
#### Post date: [July 9, 2026, 4:11pm UTC](https://meta.discourse.org/t/beginners-guide-to-using-discourse-themes/91966/54 "2026-07-09T16:11:55Z")
Welcome! thanks for mentioning it, I’ve just done a cleanup of the topic and updated the screenshots to reflect our latest version.