New: AI & text-to-SQL on your own SupersetBook a demo
D23 logoD23
All posts
Apache Superset

Apache Superset Theme Customization: White-Label Patterns

Master Apache Superset theme customization for white-label embedded analytics. Learn CSS overrides, design tokens, and production patterns.

DTD23 Team
11 minutes read

Understanding Apache Superset Theme Customization

When you're embedding analytics into your product or deploying dashboards across a portfolio of companies, visual consistency matters. Your end users shouldn't see Apache Superset branding or generic UI elements—they should see your brand. This is where Apache Superset theme customization becomes essential.

Apache Superset's theming system lets you control nearly every visual element: colors, typography, spacing, component styles, and even advanced UI patterns. Unlike legacy BI tools that force you into their aesthetic, Superset gives you the levers to build a genuinely white-labeled experience.

At D23, we've helped dozens of engineering teams and data leaders implement white-label Superset deployments—both for internal analytics platforms and embedded use cases. The difference between a quick theme swap and a production-grade white-label implementation comes down to understanding the architecture, knowing where CSS overrides belong, and following patterns that scale.

This guide walks you through the technical foundations of Superset theming, then moves into real-world white-label patterns you can implement today.

The Architecture of Superset Theming

Superset's theming system rests on three layers: the theme configuration object, CSS-in-JS styling via design tokens, and CSS override mechanisms. Understanding this stack is crucial before you start customizing.

Design Tokens and the Theme Object

At the core of Superset's theming is a JavaScript theme object that defines design tokens—reusable values for colors, typography, spacing, and shadows. These tokens cascade through the entire application via CSS variables and component-level style injection.

When you configure a theme in Superset, you're fundamentally creating or modifying a JSON object that looks something like this:

{
  "colors": {
    "primary": "#1890ff",
    "secondary": "#722ed1",
    "success": "#52c41a",
    "warning": "#faad14",
    "error": "#f5222d",
    "info": "#1890ff",
    "grayscale": {
      "base": "#000000",
      "dark": "#333333",
      "light": "#f5f5f5",
      "lighter": "#fafafa"
    }
  },
  "typography": {
    "families": {
      "base": "'Roboto', sans-serif",
      "monospace": "'Courier New', monospace"
    },
    "sizes": {
      "s": 12,
      "m": 14,
      "l": 16,
      "xl": 20
    }
  },
  "spacing": {
    "xs": 4,
    "sm": 8,
    "md": 16,
    "lg": 24,
    "xl": 32
  }
}

These tokens feed into Superset's component library, which uses them to style buttons, cards, modals, charts, and navigation elements. The advantage: change one token value and it propagates across hundreds of components.

According to the Apache Superset Official Theming Documentation, Superset 6.0 introduced a major theming overhaul that dramatically expanded customization capabilities. The framework now supports runtime theme switching, dark mode variants, and design token manipulation without requiring a rebuild.

How Superset Applies Themes

Superset uses React as its frontend framework, and themes are applied through a combination of CSS-in-JS libraries and CSS variable injection. When a user loads Superset, the theme object is converted into CSS custom properties (variables) that cascade through the DOM.

For example, a theme token like colors.primary becomes available as var(--colors-primary) in any CSS rule. This approach means you can override styles at multiple levels: globally via CSS files, component-level via theme tokens, or surgically via CSS selectors and inline styles.

Superset also leverages the Ant Design System for many of its core components. Understanding Ant Design's theming model helps you predict how customizations will cascade. Ant Design components read from the theme context and apply tokens automatically, but you can override them if needed.

Implementing White-Label Themes: The Practical Approach

White-labeling Superset means removing or replacing all visual indicators that users are running Apache Superset, and instead presenting your own branding, color scheme, typography, and UI patterns.

Step 1: Customize the Theme Object

The first step is creating a custom theme configuration. You have two paths:

Path A: UI-Based Configuration — Use Superset's built-in theme editor (available in the admin panel under Settings → Themes). This is useful for quick adjustments and testing, but it's not ideal for version control or complex deployments.

Path B: File-Based Configuration — Define your theme in Python and load it via Superset's configuration. This is the production approach because it's versionable, reviewable, and deployable via CI/CD.

Here's how to implement Path B. In your Superset configuration file (typically superset_config.py), add:

SUPERSET_THEME_OVERRIDES = {
    "colors": {
        "primary": {
            "base": "#0052CC",  # Your brand blue
            "light": "#0052CC20",  # 12% opacity for backgrounds
            "dark": "#003A99"
        },
        "secondary": "#6554C0",
        "success": "#36B37E",
        "warning": "#FFAB00",
        "error": "#DE350B",
        "grayscale": {
            "base": "#161A1D",
            "dark": "#44546F",
            "light": "#F1F2F4",
            "lighter": "#F7F8F9"
        }
    },
    "typography": {
        "families": {
            "base": "'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif",
            "monospace": "'IBM Plex Mono', monospace"
        },
        "sizes": {
            "s": 11,
            "m": 13,
            "l": 15,
            "xl": 18,
            "xxl": 22
        },
        "weights": {
            "light": 300,
            "normal": 400,
            "bold": 600
        }
    },
    "spacing": {
        "xs": 4,
        "sm": 8,
        "md": 16,
        "lg": 24,
        "xl": 32,
        "xxl": 48
    },
    "borderRadius": {
        "xs": 2,
        "sm": 4,
        "md": 8,
        "lg": 12
    }
}

This configuration becomes the baseline for your white-label theme. Every component in Superset will read from these tokens, ensuring visual consistency across the entire application.

Step 2: Override Branding Elements

Beyond the theme object, Superset has specific branding elements you'll want to customize:

Logo and Favicon — Set these in your configuration:

BRAND = {
    "name": "Your Company Analytics",
    "url": "https://yourcompany.com",
    "logo": "/path/to/your/logo.png",
    "logo_tooltip": "Your Company Analytics",
    "logo_width": 180,
    "navbar_right": {}  # Remove Superset branding from navbar
}
 
FAVICON_PATH = "/path/to/your/favicon.ico"

Navigation and Header Text — Customize the main navigation bar label and remove references to Apache Superset:

APP_NAME = "Your Company Analytics"
APP_ICON = "/path/to/your/icon.png"
LOGO_TOOLTIP = "Your Company Analytics"

Help and Support Links — Redirect users to your own documentation:

SUPERSET_HELP_LINKS = {
    "About": {"label": "About Your Company", "url": "https://yourcompany.com/about"},
    "Documentation": {"label": "Analytics Help", "url": "https://yourcompany.com/analytics-help"},
    "Slack": {"label": "Support", "url": "https://slack.yourcompany.com"},
}

These configuration changes ensure that users never see "Apache Superset" in the UI, and instead encounter your branding at every touchpoint.

CSS Overrides and Advanced Customization

The theme object handles most visual styling, but sometimes you need surgical CSS overrides for specific components or edge cases. This is where CSS customization comes in.

Using CSS Variables

Superset exposes theme tokens as CSS variables, which you can leverage in custom stylesheets. According to the Apache Superset 6.0 Unlocks Infinite Themeability guide, the latest versions of Superset support comprehensive CSS variable coverage across all components.

You can reference these variables in any CSS file:

/* Custom styles using Superset theme tokens */
.custom-dashboard-header {
  background-color: var(--colors-primary-base);
  color: var(--colors-grayscale-lighter);
  padding: var(--spacing-lg);
  font-family: var(--typography-families-base);
  border-radius: var(--border-radius-md);
}
 
.custom-metric-card {
  border: 1px solid var(--colors-grayscale-light);
  background: var(--colors-grayscale-lighter);
  padding: var(--spacing-md);
}

This approach ensures your custom styles stay in sync with your theme. If you later change your primary color, all elements using var(--colors-primary-base) update automatically.

Injecting Custom CSS

To inject custom CSS into your Superset deployment, add a reference in your configuration:

EXTRA_CATEGORICAL_TIME_FORMATS = {}
EXTRA_FILTERS_BEFORE_DATE_COMPONENTS = {}
 
# Path to custom CSS file
CUSTOM_CSS_PATH = "/path/to/custom-theme.css"

Then create your custom stylesheet with white-label overrides:

/* custom-theme.css */
 
/* Hide Superset branding elements */
[data-test="navbar-brand-link"] {
  display: none;
}
 
.navbar-brand {
  display: none !important;
}
 
/* Customize the main header */
.navbar {
  background: linear-gradient(to right, var(--colors-primary-base), var(--colors-primary-dark));
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
}
 
/* Style dashboard containers */
.dashboard-container {
  background: var(--colors-grayscale-lighter);
}
 
/* Customize button styles */
.btn-primary {
  background-color: var(--colors-primary-base);
  border-color: var(--colors-primary-base);
  border-radius: var(--border-radius-md);
  font-weight: 600;
  transition: all 0.2s ease;
}
 
.btn-primary:hover {
  background-color: var(--colors-primary-dark);
  box-shadow: 0 4px 12px rgba(0, 82, 204, 0.15);
}
 
/* Remove Superset footer attribution */
.footer {
  display: none;
}
 
/* Customize filter panels */
.filter-panel {
  background: var(--colors-grayscale-light);
  border-radius: var(--border-radius-lg);
  padding: var(--spacing-md);
}
 
/* Style metric cards */
.metric-card {
  border-radius: var(--border-radius-md);
  border: 1px solid var(--colors-grayscale-light);
  background: white;
  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.08);
}

For a deeper understanding of CSS selectors and properties, the W3C CSS Specifications and MDN Web Docs: CSS Reference are authoritative resources for advanced styling techniques.

Targeting Specific Components

Superset's React components have data attributes that make them easy to target with CSS. Common selectors include:

/* Navigation bar */
[data-test="navbar"] { }
 
/* Dashboard header */
[data-test="dashboard-header"] { }
 
/* Filter controls */
[data-test="filter-control"] { }
 
/* Chart containers */
[data-test="chart-container"] { }
 
/* Modal dialogs */
[data-test="modal-dialog"] { }
 
/* Sidebar */
[data-test="sidebar"] { }

You can inspect these attributes in your browser's developer tools and create precise CSS rules without affecting unrelated elements.

White-Label Patterns for Embedded Analytics

If you're embedding Superset dashboards into your product, white-labeling becomes even more critical. Your users should have no idea they're viewing an embedded Superset instance.

Embedding Dashboards with Custom Styling

When you embed a dashboard via the Superset API or iframe, you can pass theme parameters to ensure the embedded view matches your product's styling:

<!-- Embedded dashboard with white-label theme -->
<iframe
  src="https://superset.yourcompany.com/dashboard/123?embedded=true&theme=custom-white-label"
  width="100%"
  height="600"
  frameborder="0"
  allow="fullscreen"
></iframe>

On the Superset side, you'd define the custom-white-label theme in your configuration and ensure it matches your product's design system.

Full-Width Dashboards

For embedded use cases, you often want dashboards to consume the full viewport without Superset's navigation chrome. Configure this via:

# superset_config.py
EMBED_DASHBOARD_EXCLUDED_REGEX_PATTERNS = [
    "navbar",
    "sidebar",
    "footer",
    "superset_branding"
]

Combine this with CSS to hide remaining elements:

/* Hide navigation for embedded views */
body.embedded-view .navbar {
  display: none !important;
}
 
body.embedded-view .sidebar {
  display: none !important;
}
 
body.embedded-view .main-container {
  margin-left: 0;
  margin-top: 0;
}
 
body.embedded-view .dashboard-container {
  padding: 0;
}

Dark Mode Support

Modern applications often support dark mode. Superset's theming system allows you to define dark and light variants:

SUPERSET_THEME_OVERRIDES = {
    "light": {
        "colors": {
            "primary": "#0052CC",
            "grayscale": {
                "base": "#161A1D",
                "light": "#F1F2F4",
                "lighter": "#F7F8F9"
            }
        }
    },
    "dark": {
        "colors": {
            "primary": "#4589FF",
            "grayscale": {
                "base": "#F7F8F9",
                "light": "#44546F",
                "lighter": "#161A1D"
            }
        }
    }
}

Users can then toggle between themes, and your custom CSS will automatically adapt using CSS variables.

Production Deployment Patterns

White-labeling Superset for production requires more than just configuration changes. You need to think about versioning, testing, and rollback.

Version Control and CI/CD

Store your theme configuration and custom CSS in version control:

# Project structure
/superset-deployment
  /config
    superset_config.py
    theme-overrides.json
  /static
    custom-theme.css
    logo.png
    favicon.ico
  /docker
    Dockerfile
    docker-compose.yml

Your CI/CD pipeline should validate theme configuration before deployment:

# Example GitHub Actions workflow
name: Deploy Superset Theme
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Validate theme configuration
        run: python scripts/validate_theme.py
      - name: Build Docker image
        run: docker build -t superset:white-label .
      - name: Deploy to production
        run: kubectl apply -f k8s/superset-deployment.yaml

Testing Theme Changes

Before deploying theme changes to production, test them thoroughly:

  1. Visual Testing — Take screenshots across different browsers and devices to ensure consistency
  2. Component Testing — Verify that all interactive elements (buttons, filters, modals) work correctly with your custom styles
  3. Performance Testing — Ensure custom CSS doesn't introduce layout thrashing or slow rendering
  4. Accessibility Testing — Verify that color contrasts meet WCAG standards and that your theme doesn't break keyboard navigation

You can automate visual testing with tools like Percy or Chromatic, which integrate with your CI/CD pipeline.

Rollback Strategy

If a theme deployment causes issues, you need a quick rollback path:

# Tag releases
git tag -a v1.2.0-theme -m "White-label theme release"
git push origin v1.2.0-theme
 
# Rollback to previous version
git checkout v1.1.0-theme
docker build -t superset:v1.1.0-theme .
kubectl set image deployment/superset superset=superset:v1.1.0-theme

Always maintain at least two previous theme versions in production so you can roll back quickly if needed.

Advanced Customization with Component Overrides

For truly custom experiences, you can override individual React components. This requires deeper knowledge of Superset's architecture and is typically needed for complex embedded scenarios.

Custom Chart Renderers

If you want to render charts with completely custom styling, you can create a custom chart plugin:

// custom-chart-plugin.ts
import { ChartPlugin } from '@superset-ui/core';
import CustomChartComponent from './CustomChartComponent';
 
const customChartPlugin = new ChartPlugin({
  name: 'custom-branded-chart',
  metadata: {
    category: 'Custom',
    description: 'Custom branded chart component',
  },
  loadChart: () => CustomChartComponent,
});
 
export default customChartPlugin;

This approach gives you complete control over how data is visualized while maintaining integration with Superset's data pipeline.

Custom Filter Components

Similarly, you can create custom filter components that match your product's interaction patterns:

// CustomFilterComponent.tsx
import React from 'react';
import { useTheme } from '@superset-ui/core';
 
const CustomFilterComponent: React.FC<Props> = (props) => {
  const theme = useTheme();
  
  return (
    <div
      style={{
        backgroundColor: theme.colors.grayscale.light,
        borderRadius: theme.borderRadius.md,
        padding: theme.spacing.md,
      }}
    >
      {/* Your custom filter UI */}
    </div>
  );
};
 
export default CustomFilterComponent;

These custom components still read from your theme tokens, ensuring visual consistency.

Measuring White-Label Success

After implementing your white-label theme, track these metrics to ensure success:

Visual Consistency — Are all UI elements rendering with your brand colors and typography? Use automated visual testing to catch regressions.

User Perception — Conduct user testing to verify that users perceive the dashboards as part of your product, not a third-party tool.

Performance — Monitor page load times and interaction latency. Custom CSS should have minimal performance impact, but it's worth tracking.

Support Tickets — Track issues related to theming or visual inconsistencies. A drop in theme-related tickets indicates successful implementation.

Common Pitfalls and Solutions

Pitfall 1: Over-Reliance on !important

Using !important in CSS creates brittle stylesheets that are hard to maintain. Instead, use higher CSS specificity:

/* Bad */
.btn { color: blue !important; }
 
/* Good */
body.white-label .btn {
  color: var(--colors-primary-base);
}

Pitfall 2: Inconsistent Theme Values Across Environments

Ensure your theme configuration is identical across development, staging, and production. Use environment variables to manage environment-specific values:

import os
 
PRIMARY_COLOR = os.getenv('BRAND_PRIMARY_COLOR', '#0052CC')
SUPERSET_THEME_OVERRIDES = {
    "colors": {
        "primary": PRIMARY_COLOR
    }
}

Pitfall 3: Forgetting About Responsive Design

Your white-label theme must work on mobile, tablet, and desktop. Test extensively on different screen sizes and use responsive CSS:

@media (max-width: 768px) {
  .navbar {
    padding: var(--spacing-sm);
  }
  
  .dashboard-grid {
    grid-template-columns: 1fr;
  }
}

Pitfall 4: Ignoring Accessibility

When customizing colors, ensure sufficient contrast for readability. Use tools like WebAIM's contrast checker to verify WCAG compliance:

/* Ensure text is readable */
.dashboard-header {
  background-color: var(--colors-primary-base);
  color: #ffffff;  /* High contrast */
}

Integrating with D23's Managed Superset

If you're using D23 for managed Apache Superset hosting, white-labeling becomes significantly simpler. D23 handles the infrastructure, updates, and scaling, while you focus on customization and analytics strategy.

D23's platform includes built-in support for theme customization, allowing you to:

  • Upload custom logos and branding assets via the dashboard
  • Configure theme tokens without touching code
  • Deploy theme changes instantly without restarting services
  • Manage multiple white-label instances for different brands or clients

For teams building embedded analytics or managing analytics across multiple portfolio companies, this managed approach eliminates the operational overhead of self-hosted Superset while maintaining full customization capabilities.

You can also leverage D23's API-first architecture to programmatically manage themes across multiple Superset instances, which is particularly valuable for private equity or venture capital firms standardizing analytics across their portfolios.

Conclusion

Apache Superset's theming system is powerful and flexible, but white-labeling successfully requires understanding the architecture, following production patterns, and testing thoroughly. By starting with theme tokens, layering in CSS overrides, and testing across environments, you can build white-label analytics experiences that feel native to your product.

The key is treating theme customization as code: version it, test it, and deploy it with the same rigor as any other product change. Done right, your users will never know they're running Superset—they'll just see your brand, your colors, and your analytics.

For teams looking to accelerate this process without managing infrastructure, D23's managed Superset platform provides built-in white-labeling tools and expert consulting to get you from zero to production-grade embedded analytics in weeks, not months. Whether you're embedding dashboards in your product, standardizing analytics across a portfolio, or building a self-serve BI platform, the patterns in this guide will help you achieve a truly branded experience.