Include images and fonts in themes and components

Themes and theme components allow you to handle uploaded assets such as images and fonts. You can control what assets your theme accepts using the site setting: theme authorized extensions

There are two classifications of themes and components - local and remote.


  • The default Light and Dark themes that ship with every Discourse instance
  • Themes and components created using the + Create New installation method
  • Themes and components that were uploaded from your local computer using the From your device installation method.


  • Themes and components installed from the Popular list of themes
  • Themes and components installed using the From a git repository method

Uploading assets to local themes and components

Navigate to your theme or component and select + Add in the Uploads section:

In the Add Upload modal, choose a file and enter a SCSS variable name to use with with your CSS, javascript, and/or handlbars customizations

Once uploaded, the asset will pop up in the Uploads list:


:warning: Important Note: Do not add uploads to themes and components through the admin interface if the component was installed remotely from a git repository. Updates to the component will clear out any uploads that were not included in the git repository.

Including assets in remote themes and components

See Create and share a font theme component for a detailed example.

How to make use of the assets


@font-face {
  font-family: Amazing;
  src: url($Comic-Sans) format('woff2')

body {
    font-family: Amazing;
    font-size: 15px;

.d-header {
    background-image: url($texture);


<script type="text/discourse-plugin" version="0.8">


<script type="text/x-handlebars" data-template-name="/connectors/topic-above-post-stream/foobar">
  <img src="{{theme-setting "theme_uploads.balloons"}}">

You can’t directly add a theme asset to vanilla HTML (like in the header or after header sections of the customize admin panel). You have to use a handlebars template or the plugin API (more about those in Developer’s guide to Discourse Themes).

One workaround is to load your asset as a background image using SCSS (like the example above). So in the header section of your theme you might add:

<div class="my-custom-div">
  <a href="/"></a>

and then in your CSS:

.my-custom-div a {
    height: 50px;
    width: 100px; 
    background-image: url($asset-name);

Additional Information

Treat theme_uploads as Settings in JavaScript
This has been implemented here:

This change allows themes and components access to theme assets.

This means that inside theme js you can now get the URL for an asset with:

You can now do:

handlebars: {{theme-setting "theme_uploads.balloons"}}

javascript: settings.theme_uploads.balloons

Last Reviewed by @AlexDev on 2022-06-10T20:00:00Z