Include assets (e.g. images, 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

Including assets in themes and components

For remote themes

Remote themes include:

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

To upload assets to a remote theme or theme component, see Create and share a font theme component for a detailed example.

Uploading assets to local themes and components

Local themes include:

  • 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.

To upload assets to a local theme or theme component, 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.

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);

:information_source: When using ttf or otf fonts, be sure to use a format of opentype.


<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 Beginner's guide to developing 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);

Accessing theme uploads as settings

You may also treat theme_uploads as settings in JavaScript (related commit).

This allows themes and components access to theme assets.

Inside theme js you can now get the URL for an asset with:

And then you can do:

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

javascript: settings.theme_uploads.balloons

Additional Information

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

Last edited by @JammyDodger 2024-05-26T12:25:19Z

Check documentPerform check on document: