docs/admin_docs/configuration/theming.mdx

---
title: Theming
hide_title: true
sidebar_position: 12
version: 1
---
# 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](https://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
```

### App Branding

The application name shown in the browser title bar and navigation can be
set via the `brandAppName` theme token:

```python
THEME_DEFAULT = {
    "token": {
        "brandAppName": "Acme Analytics",
        # ... other tokens
    }
}
```

Or in the theme CRUD UI JSON editor:

```json
{
  "token": {
    "brandAppName": "Acme Analytics"
  }
}
```

The existing `APP_NAME` Python config key continues to work for backward compatibility.
`brandAppName` takes precedence when both are set, and allows different themes to carry different brand names.
Email and alert/report notification subjects are driven by backend settings such as
`EMAIL_REPORTS_SUBJECT_PREFIX` and `APP_NAME`, not by this theme token.

### 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

### Theme Validation and Fallback

Superset validates theme JSON when it is saved, either through the UI or via configuration. If a theme contains invalid tokens or an unrecognized structure, Superset logs a warning and falls back to the built-in default theme rather than applying a broken configuration. This prevents a bad theme from rendering the application unusable.

The fallback order is:
1. **UI-configured system theme** (highest priority, if `ENABLE_UI_THEME_ADMINISTRATION = True`)
2. **`THEME_DEFAULT` / `THEME_DARK`** from `superset_config.py`
3. **Built-in Superset default theme** (always present as a safety net)

If you see unexpected styling after a config change, check the Superset server logs for theme validation warnings.

### 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](https://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** for UI text and **IBM Plex Mono** for code (SQL editors, JSON fields, and other monospace contexts). Both fonts are bundled with the application via `@fontsource` packages and work offline without any external network calls.

:::note
IBM Plex Mono replaced Fira Code as the default code font in Superset 6.1. If you have an existing theme that explicitly sets `fontFamilyCode: "Fira Code, ..."`, you may want to update it.
:::

### 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

### Array Property Overrides

Array properties (such as color palettes) are fully supported in overrides. Arrays are **replaced entirely** rather than merged, so specify the complete array:

```python
THEME_DEFAULT = {
    "token": { ... },
    "echartsOptionsOverrides": {
        # Replace the default color palette for all ECharts visualizations
        "color": ["#1f77b4", "#ff7f0e", "#2ca02c", "#d62728", "#9467bd", "#8c564b"]
    }
}
```

### 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 for objects, but arrays are completely replaced — always specify the full array value
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
- [Video: Live Demo — Theming Apache Superset](https://www.youtube.com/watch?v=XsZAsO9tC3o)
- [CSS and Theming](https://docs.preset.io/docs/css-and-theming) - Additional theming techniques and CSS customization
- [Blog: Customizing Apache Superset Dashboards with CSS](https://preset.io/blog/customizing-superset-dashboards-with-css/)
- [Blog: Customizing Dashboards with CSS — Tips and Tricks](https://preset.io/blog/customizing-apache-superset-dashboards-with-css-additional-tips-and-tricks/)
- [Blog: Customizing Chart Colors](https://preset.io/blog/customizing-chart-colors-with-superset-and-preset/)
:::