Theming Superset

note

apache-superset>=6.0

Superset now rides on Ant Design v5's token-based theming. Every Antd token works, plus a handful of Superset-specific ones for charts and dashboard chrome.

Managing Themes via CRUD Interface

Superset now includes a built-in Theme Management interface accessible from the admin menu under Settings > Themes.

Creating a New Theme

Navigate to Settings > Themes in the Superset interface
Click + Theme to create a new theme
Use the Ant Design Theme Editor to design your theme:
- Design your palette, typography, and component overrides
- Open the CONFIG modal and copy the JSON configuration
Paste the JSON into the theme definition field in Superset
Give your theme a descriptive name and save

You can also extend with Superset-specific tokens (documented in the default theme object) before you import.

Applying Themes to Dashboards

Once created, themes can be applied to individual dashboards:

Edit any dashboard and select your custom theme from the theme dropdown
Each dashboard can have its own theme, allowing for branded or context-specific styling

Alternative: Instance-wide Configuration

For system-wide theming, you can configure default themes via Python configuration:

Setting Default Themes

# superset_config.py

# Default theme (light mode)
THEME_DEFAULT = {
    "token": {
        "colorPrimary": "#2893B3",
        "colorSuccess": "#5ac189",
        # ... your theme JSON configuration
    }
}

# Dark theme configuration
THEME_DARK = {
    "algorithm": "dark",
    "token": {
        "colorPrimary": "#2893B3",
        # ... your dark theme overrides
    }
}

# Theme behavior settings
THEME_SETTINGS = {
    "enforced": False,          # If True, forces default theme always
    "allowSwitching": True,     # Allow users to switch between themes
    "allowOSPreference": True,  # Auto-detect system theme preference
}

Copying Themes from CRUD Interface

To use a theme created via the CRUD interface as your system default:

Navigate to Settings > Themes and edit your desired theme
Copy the complete JSON configuration from the theme definition field
Paste it directly into your superset_config.py as shown above

Restart Superset to apply changes.

Theme Development Workflow

Design: Use the Ant Design Theme Editor to iterate on your design
Test: Create themes in Superset's CRUD interface for testing
Apply: Assign themes to specific dashboards or configure instance-wide
Iterate: Modify theme JSON directly in the CRUD interface or re-import from the theme editor

Custom Fonts

Superset supports custom fonts through runtime configuration, allowing you to use branded or custom typefaces without rebuilding the application.

Configuring Custom Fonts

Add font URLs to your superset_config.py:

# Load fonts from Google Fonts, Adobe Fonts, or self-hosted sources
CUSTOM_FONT_URLS = [
    "https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap",
    "https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500&display=swap",
]

# Update CSP to allow font sources
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"],
    }
}

Using Custom Fonts in Themes

Once configured, reference the fonts in your theme configuration:

THEME_DEFAULT = {
    "token": {
        "fontFamily": "Inter, -apple-system, BlinkMacSystemFont, sans-serif",
        "fontFamilyCode": "JetBrains Mono, Monaco, monospace",
        # ... other theme tokens
    }
}

Or in the CRUD interface theme JSON:

{
  "token": {
    "fontFamily": "Inter, -apple-system, BlinkMacSystemFont, sans-serif",
    "fontFamilyCode": "JetBrains Mono, Monaco, monospace"
  }
}

Font Sources

Google Fonts: Free, CDN-hosted fonts with wide variety
Adobe Fonts: Premium fonts (requires subscription and kit ID)
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!

Superset provides the capability for dynamic, theme-driven branding of its login page, enabling organizations to personalize the login screen with custom background images and login form logos.

Superset supports the following optional theme tokens to customize the login page appearance:

loginPageBackgroundImageUrl: URL of the login page background image
loginFormBrandLogoUrl: URL of the logo displayed on the login form
loginPageBackgroundOverlayColor: overlay color applied on top of the background image to improve contrast and readability
loginPageBackgroundBlur: CSS blur radius applied to the login page background image (e.g., 4px, 0.25rem, 1em, 10vw)

If these tokens are omitted, Superset’s default login page styling is used.

The loginPageBackgroundOverlayColor token accepts any valid CSS color format, including:

Hex (e.g., #000000)
Hex with alpha (e.g., #00000080)
RGB/RGBA (e.g., rgba(0, 0, 0, 0.5))
HSL/HSLA (e.g., hsla(0, 0%, 0%, 0.5))
Named colors (e.g., black)

If loginPageBackgroundImageUrl is provided but loginPageBackgroundOverlayColor is omitted, the overlay defaults to a semi-transparent black: rgba(0, 0, 0, 0.5). The default value for loginPageBackgroundBlur is 0px (no blur effect on the background image).

Tokens for login page customization can be set within the JSON theme configuration defined either in superset_config.py:

# superset_config.py

THEME_DEFAULT = {
    "token": {
        "loginPageBackgroundImageUrl": "/static/assets/images/login-background.jpg",
        "loginFormBrandLogoUrl": "/static/assets/images/superset-logo-horiz.png",
        "loginPageBackgroundOverlayColor": "rgba(0, 0, 0, 0.6)",
        "loginPageBackgroundBlur": "3px"
        # ... other theme tokens
    }
}

Or directly via the CRUD interface on the Themes page.

{
   "token": {
        "loginPageBackgroundImageUrl": "/static/assets/images/login-background.jpg",
        "loginFormBrandLogoUrl": "/static/assets/images/superset-logo-horiz.png",
        "loginPageBackgroundOverlayColor": "rgba(0, 0, 0, 0.6)",
        "loginPageBackgroundBlur": "3px"
    }
}

Advanced Features

System Themes: Superset includes built-in light and dark themes
Per-Dashboard Theming: Each dashboard can have its own visual identity
JSON Editor: Edit theme configurations directly within Superset's interface
Custom Fonts: Load external fonts via configuration without rebuilding
Login Page Customization: Customize login page visuals through theme tokens

Managing Themes via CRUD Interface​

Creating a New Theme​

Applying Themes to Dashboards​

Alternative: Instance-wide Configuration​

Setting Default Themes​

Copying Themes from CRUD Interface​

Theme Development Workflow​

Custom Fonts​

Configuring Custom Fonts​

Using Custom Fonts in Themes​

Font Sources​

Login Page Customization​

Customizing the Login Page via Theme Tokens in Theme JSON​

Advanced Features​