ContextQMD
Back to Superset

Theming

docs/admin_docs/configuration/theming.mdx

2021.41.013.0 KB
Original Source

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 UI

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

System Theme Administration

When ENABLE_UI_THEME_ADMINISTRATION = True is configured, administrators can manage system-wide themes directly from the UI:

Setting System Themes

  • System Default Theme: Click the sun icon on any theme to set it as the system-wide default
  • System Dark Theme: Click the moon icon on any theme to set it as the system dark mode theme
  • Automatic OS Detection: When both default and dark themes are set, Superset automatically detects and applies the appropriate theme based on OS preferences

Managing System Themes

  • System themes are indicated with special badges in the theme list
  • Only administrators with write permissions can modify system theme settings
  • Removing a system theme designation reverts to configuration file defaults

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

Configuration Options

Python Configuration

Configure theme behavior via superset_config.py:

python
# Enable UI-based theme administration for admins
ENABLE_UI_THEME_ADMINISTRATION = True

# Optional: Set initial default themes via configuration
# These can be overridden via the UI when ENABLE_UI_THEME_ADMINISTRATION = True
THEME_DEFAULT = {
    "token": {
        "colorPrimary": "#2893B3",
        "colorSuccess": "#5ac189",
        # ... your theme JSON configuration
    }
}

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

# To force a single theme on all users, set THEME_DARK = None
# When both themes are defined (via UI or config):
# - Users can manually switch between themes
# - OS preference detection is automatically enabled

Migration from Configuration to UI

When ENABLE_UI_THEME_ADMINISTRATION = True:

  1. System themes set via the UI take precedence over configuration file settings
  2. The UI shows which themes are currently set as system defaults
  3. Administrators can change system themes without restarting Superset
  4. Configuration file themes serve as fallbacks when no UI themes are set

Copying Themes Between Systems

To export a theme for use in configuration files or another instance:

  1. Navigate to Settings > Themes and click the export icon on your desired theme
  2. Extract the JSON configuration from the exported YAML file
  3. Use this JSON in your superset_config.py or import it into another Superset instance

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 the theme configuration, allowing you to use branded or custom typefaces without rebuilding the application.

Default Fonts

By default, Superset uses Inter and Fira Code fonts which are bundled with the application via @fontsource packages. These fonts work offline and require no external network calls.

Configuring Custom Fonts

To use custom fonts, add font URLs to your theme configuration using the fontUrls token:

python
THEME_DEFAULT = {
    "token": {
        # Load fonts from external sources (e.g., Google Fonts, Adobe Fonts)
        "fontUrls": [
            "https://fonts.googleapis.com/css2?family=Roboto:wght@400;500;600;700&display=swap",
            "https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500&display=swap",
        ],
        # Reference the loaded fonts
        "fontFamily": "Roboto, -apple-system, BlinkMacSystemFont, sans-serif",
        "fontFamilyCode": "JetBrains Mono, Monaco, monospace",
        # ... other theme tokens
    }
}

# 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"],
    }
}

Or in the CRUD interface theme JSON:

json
{
  "token": {
    "fontUrls": [
      "https://fonts.googleapis.com/css2?family=Roboto:wght@400;500;600;700&display=swap"
    ],
    "fontFamily": "Roboto, -apple-system, BlinkMacSystemFont, sans-serif",
    "fontFamilyCode": "JetBrains Mono, Monaco, monospace"
  }
}

:::note Font URLs are validated against a configurable allowlist. By default, fonts from fonts.googleapis.com, fonts.gstatic.com, and use.typekit.net are allowed. Configure THEME_FONT_URL_ALLOWED_DOMAINS to customize the allowed domains. :::

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!

ECharts Configuration Overrides

:::note Available since Superset 6.0 :::

Superset provides fine-grained control over ECharts visualizations through theme-level configuration overrides. This allows you to customize the appearance and behavior of all ECharts-based charts without modifying individual chart configurations.

Global ECharts Overrides

Apply settings to all ECharts visualizations using echartsOptionsOverrides:

python
THEME_DEFAULT = {
    "token": {
        "colorPrimary": "#2893B3",
        # ... other Ant Design tokens
    },
    "echartsOptionsOverrides": {
        "grid": {
            "left": "10%",
            "right": "10%",
            "top": "15%",
            "bottom": "15%"
        },
        "tooltip": {
            "backgroundColor": "rgba(0, 0, 0, 0.8)",
            "borderColor": "#ccc",
            "textStyle": {
                "color": "#fff"
            }
        },
        "legend": {
            "textStyle": {
                "fontSize": 14,
                "fontWeight": "bold"
            }
        }
    }
}

Chart-Specific Overrides

Target specific chart types using echartsOptionsOverridesByChartType:

python
THEME_DEFAULT = {
    "token": {
        "colorPrimary": "#2893B3",
        # ... other tokens
    },
    "echartsOptionsOverridesByChartType": {
        "echarts_pie": {
            "legend": {
                "orient": "vertical",
                "right": 10,
                "top": "center"
            }
        },
        "echarts_timeseries": {
            "xAxis": {
                "axisLabel": {
                    "rotate": 45,
                    "fontSize": 12
                }
            },
            "dataZoom": [{
                "type": "slider",
                "show": True,
                "start": 0,
                "end": 100
            }]
        },
        "echarts_bubble": {
            "grid": {
                "left": "15%",
                "bottom": "20%"
            }
        }
    }
}

UI Configuration

You can also configure ECharts overrides through the theme CRUD interface:

json
{
  "token": {
    "colorPrimary": "#2893B3"
  },
  "echartsOptionsOverrides": {
    "grid": {
      "left": "10%",
      "right": "10%"
    },
    "tooltip": {
      "backgroundColor": "rgba(0, 0, 0, 0.8)"
    }
  },
  "echartsOptionsOverridesByChartType": {
    "echarts_pie": {
      "legend": {
        "orient": "vertical",
        "right": 10
      }
    }
  }
}

Override Precedence

The system applies overrides in the following order (last wins):

  1. Base ECharts theme - Default Superset styling
  2. Plugin options - Chart-specific configurations
  3. Global overrides - echartsOptionsOverrides
  4. Chart-specific overrides - echartsOptionsOverridesByChartType[chartType]

This ensures chart-specific overrides take precedence over global ones.

Common Chart Types

Available chart types for echartsOptionsOverridesByChartType:

  • echarts_timeseries - Time series/line charts
  • echarts_pie - Pie and donut charts
  • echarts_bubble - Bubble/scatter charts
  • echarts_funnel - Funnel charts
  • echarts_gauge - Gauge charts
  • echarts_radar - Radar charts
  • echarts_boxplot - Box plot charts
  • echarts_treemap - Treemap charts
  • echarts_sunburst - Sunburst charts
  • echarts_graph - Network/graph charts
  • echarts_sankey - Sankey diagrams
  • echarts_heatmap - Heatmaps
  • echarts_mixed_timeseries - Mixed time series

Best Practices

  1. Start with global overrides for consistent styling across all charts
  2. Use chart-specific overrides for unique requirements per visualization type
  3. Test thoroughly as overrides use deep merge - nested objects are combined, but arrays are completely replaced
  4. Document your overrides to help team members understand custom styling
  5. Consider performance - complex overrides may impact chart rendering speed

Example: Corporate Branding

python
# Complete corporate theme with ECharts customization
THEME_DEFAULT = {
    "token": {
        "colorPrimary": "#1B4D3E",
        "fontFamily": "Corporate Sans, Arial, sans-serif"
    },
    "echartsOptionsOverrides": {
        "grid": {
            "left": "8%",
            "right": "8%",
            "top": "12%",
            "bottom": "12%"
        },
        "textStyle": {
            "fontFamily": "Corporate Sans, Arial, sans-serif"
        },
        "title": {
            "textStyle": {
                "color": "#1B4D3E",
                "fontSize": 18,
                "fontWeight": "bold"
            }
        }
    },
    "echartsOptionsOverridesByChartType": {
        "echarts_timeseries": {
            "xAxis": {
                "axisLabel": {
                    "color": "#666",
                    "fontSize": 11
                }
            }
        },
        "echarts_pie": {
            "legend": {
                "textStyle": {
                    "fontSize": 12
                },
                "itemGap": 20
            }
        }
    }
}

This feature provides powerful theming capabilities while maintaining the flexibility of ECharts' extensive configuration options.

Advanced Features

  • System Themes: Manage system-wide default and dark themes via UI or configuration
  • 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
  • OS Dark Mode Detection: Automatically switches themes based on system preferences
  • Theme Import/Export: Share themes between instances via YAML files

API Access

For programmatic theme management, Superset provides REST endpoints:

  • GET /api/v1/theme/ - List all themes
  • POST /api/v1/theme/ - Create a new theme
  • PUT /api/v1/theme/{id} - Update a theme
  • DELETE /api/v1/theme/{id} - Delete a theme
  • PUT /api/v1/theme/{id}/set_system_default - Set as system default theme (admin only)
  • PUT /api/v1/theme/{id}/set_system_dark - Set as system dark theme (admin only)
  • DELETE /api/v1/theme/unset_system_default - Remove system default designation
  • DELETE /api/v1/theme/unset_system_dark - Remove system dark designation
  • GET /api/v1/theme/export/ - Export themes as YAML
  • POST /api/v1/theme/import/ - Import themes from YAML

These endpoints require appropriate permissions and are subject to RBAC controls.

:::resources