Recommended approach to add custom fonts with the new theming system and frontend structure

[VasilijeBursac]

Hi everyone,

I'm customizing the Superset UI and I’d like to add custom fonts so that they can be used globally via the fontFamily Ant Design token in the theme JSON (within general and dashboard themes).

I’ve found older threads suggesting the use of fonts.less or similar approaches, such as the one shown in the image below:

Since Superset is moving away from LESS and global CSS toward Ant Design v5 tokens and more JS-based theming, I’d like to ask:

• What is the most future-proof and currently recommended way to load and register custom fonts so they can be used in Ant Design fontFamily tokens across all components?
• Can this be done without maintaining a custom fork of Superset's frontend?
• If some changes to the frontend code are unavoidable, what’s the minimal set of modifications needed?
• Ideally, I want a solution that can be easily integrated into multiple Superset projects with minimal additional work.

I'd be very thankful if both cases could be explained, i.e.:

• Hosting fonts locally, e.g., placing font files in /static/assets/fonts/
• Loading fonts from external sources, such as Google Fonts CDN or using the @fontsource package.
  Where would the imports ideally go in each case? For example, is Theme.tsx the right place to load them globally?

I’d really appreciate clarification or confirmation on the best practice, especially regarding how Superset expects custom fonts to be loaded in this new setup.

Apologies if tagging is inappropriate, but I've seen the following folks be especially active in theming and frontend customization PRs, so I hope it’s okay to mention you for insights: @gabotorresruiz @msyavuz @eschutho @geido @mistercrunch @rusackas @EnxDev

Thanks in advance for your time and help.
Best regards!

[dosubot[bot]]

Hi @VasilijeBursac! I'm Dosu and I’m helping the superset team.

The most future-proof way to load custom fonts in Superset’s new theming system is to import your font files (via @fontsource, a CSS file, or @font-face) at the top of Theme.tsx in the frontend. This ensures the fonts are available globally and can be referenced in the Ant Design fontFamily token in your theme JSON or config. The theme token only sets the CSS font-family property; it does not load the font itself—so you must ensure the font is loaded before referencing it in the theme config.

For local fonts, place your font files in /static/assets/fonts/, create a CSS file with @font-face rules pointing to those files, and import that CSS file at the top of Theme.tsx. For external fonts (like Google Fonts or @fontsource), import the relevant CSS or JS package at the top of Theme.tsx as well. If you use Google Fonts or another CDN, make sure to update the Content Security Policy (CSP) in TALISMAN_CONFIG in config.py to allow those font sources, or the browser will block them example.

You do not need to maintain a custom fork if you can inject your font imports early in the frontend entry hierarchy or via a plugin, but to guarantee global font availability for all users, a minimal code change—importing your font CSS or @fontsource package in Theme.tsx—is the standard approach example. Theme.tsx is the canonical place for these imports in the new setup.

Once the font is loaded, set the fontFamily token in your theme JSON/config to the font’s CSS name (e.g., 'My Custom Font', Arial, sans-serif). This will apply it globally via the theming system example.

There’s no built-in mechanism to load fonts via theme JSON alone; font files must be loaded separately and referenced by name in the theme config. This approach is reusable across projects: just import your font(s) in Theme.tsx and reference them in your theme tokens.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[msyavuz]

Right now i think the best place to load custom fonts in is the Theme.tsx file imports, but i agree that we can make the experience better by providing a standardized way of loading custom fonts with something like a config option or inside the Theme crud

[mistercrunch]

Yeah would be great to have support to something AFTER webpack builds. Ideally you'd reference a CDN and we'd get the fonts in the background. The best place I can point to is https://github.com/apache/superset/blob/master/superset/templates/superset/spa.html , like you'd have to dust off the jinja2 docs and figure out how to add a section like {% block fonts %} or something and couple that to a superset/config.py things like FONT_URLS and maybe have a jinja macro to transform those urls in to HTML

[mistercrunch]

I asked Claude Code to analyze this, here's what it came up with (after going nuts on SUPER complex solutions...)

---

Simple Runtime Font Loading for Superset

You're exactly right! The solution is quite straightforward:

Implementation

1. Add font config to superset_config.py:

CUSTOM_FONT_URLS = [
    "https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap",
    "https://fonts.googleapis.com/css2?family=Roboto+Mono&display=swap"
]

# Update CSP to allow these domains
TALISMAN_CONFIG = {
    "content_security_policy": {
        "font-src": ["'self'", "https://fonts.googleapis.com", "https://fonts.gstatic.com"],
        "style-src": ["'self'", "'unsafe-inline'", "https://fonts.googleapis.com"],
    }
}

2. Modify the Jinja base template (superset/templates/superset/spa.html):

{% if config.CUSTOM_FONT_URLS %}
  {% for font_url in config.CUSTOM_FONT_URLS %}
    <link rel="stylesheet" href="{{ font_url }}">
  {% endfor %}
{% endif %}

3. Use the fonts normally in theme config or CSS:

{
  "token": {
    "fontFamily": "Inter, -apple-system, BlinkMacSystemFont, sans-serif"
  }
}

How It Works

• Config defines font URLs
• Jinja template injects <link> tags at runtime
• Browser loads fonts from CDN
• React/Ant Design components can reference them by name
• No build required!

This gives Docker users custom fonts through simple configuration, while build users can still bundle fonts the traditional way.

[VasilijeBursac]

@mistercrunch Thank you for this amazing work! It’s a very useful feature, and I really appreciate the flexibility it provides.

I've been experimenting with custom fonts and successfully tested using Google Fonts. I have a few follow-up questions related to the self-hosted font setup and best practices for integration:

1. Self-hosted fonts setup

The documentation states:

"Self-hosted: Place font files in /static/assets/fonts/ and reference via CSS. This feature works with the stock Docker image - no custom build required!"

Could you please provide a minimal working example of this setup? Specifically:

• What is the recommended CSS entry point for loading the font in a generic and upgrade-safe way (i.e., without maintaining custom frontend code)?
• Can a separate CSS file be created to handle font declarations, and then be loaded via superset_config.py?

2. Required font weights

What font weights need to be included to completely replace all Superset UI fonts (including the code editor)?
Are the weights imported in GlobalStyles.tsx sufficient? From what I saw, these are:

• 200, 400, 500, 600 for general UI elements
• 400, 500, 600 for the code editor fonts

3. Support for variable fonts

Does Superset currently support variable fonts? If so, are there any known limitations or considerations when using them?

Thanks again for your time and support.

Best regards!

[mistercrunch]

Let me try to have AI generate a PR see how far it gets

[mistercrunch]

Here #34416

[VasilijeBursac]

@dosu

The documentation states:

"Self-hosted: Place font files in /static/assets/fonts/ and reference via CSS. This feature works with the stock Docker image - no custom build required!"

Could you please provide a minimal working example of this setup? Specifically:

1. What is the recommended CSS entry point for loading the font in a generic and upgrade-safe way (i.e., without maintaining custom frontend code)?
2. Can a separate CSS file be created to handle font declarations, and then be loaded via superset_config.py?

[dosubot[bot]]

Superset does not currently support loading a separate CSS file for self-hosted fonts via superset_config.py—that config is only for external font URLs (like Google Fonts) injected at runtime. For self-hosted fonts, the most upgrade-safe approach is to place your font files in /static/assets/fonts/, create a fonts.css file in that folder with your @font-face rules referencing those files, and then inject <link rel="stylesheet" href="/static/assets/fonts/fonts.css"> into the global template (such as spa.html or basic.html) using the head_css block. This requires a manual template extension or edit, not a config change, and may need maintenance after upgrades. Reference

If you want to avoid frontend code changes, template extension is the best practice for now. Monitor future releases for config-driven CSS injection features.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}