Skip to main content

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​

  1. Navigate to Settings > Themes in the Superset interface
  2. Click + Theme to create a new theme
  3. 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
  4. Paste the JSON into the theme definition field in Superset
  5. 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:

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

Restart Superset to apply changes.

Theme Development Workflow​

  1. Design: Use the Ant Design Theme Editor to iterate on your design
  2. Test: Create themes in Superset's CRUD interface for testing
  3. Apply: Assign themes to specific dashboards or configure instance-wide
  4. 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!

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