Setting up Themes in Preset

Customize the appearance of your Preset workspace and dashboards with token-based theming. Create branded experiences that align with your organization's visual identity.

Overview

Preset uses Ant Design v5's token-based theming system, allowing you to customize colors, typography, spacing, and component styling across your workspace. You can create multiple themes and apply them at different levels:

• Workspace-wide themes: Set default and dark mode themes for your entire workspace
• Dashboard-specific themes: Apply themes to individual dashboards
• Chart customizations: Fine-tune ECharts visualizations within your themes (chart styling is configured at the theme level and applies wherever that theme is used—workspace-wide or on specific dashboards)

Themes in Preset are the recommended approach for customization, as they're more maintainable and less brittle than CSS overrides.

Looking for inspiration? Check out our Theme Gallery for pre-built themes you can copy and customize for your workspace.

Creating a New Theme

Permissions required: Workspace Admin

Step 1: Design Your Theme

1. Navigate to Settings > Themes in Preset
2. Click + Theme to create a new theme
3. Open the Ant Design Theme Editor in a new tab
4. Design your theme by customizing:
   • Colors: Primary colors, success/warning/error states, and backgrounds
   • Typography: Font families, sizes, and weights
   • Components: Buttons, inputs, cards, and other interface elements
5. When finished, click the Config button in the theme editor
6. Copy the JSON configuration from the modal

Step 2: Add your Theme into Preset

1. Return to Preset and paste the JSON into the theme definition field
2. Give your theme a descriptive name (e.g., "Corporate Brand - Light")
3. Click Add

Your theme is now available to use in your workspace.

Preset-Specific Tokens

In addition to standard Ant Design tokens, you can extend your theme with Preset-specific customizations:

Brand Logo:

json
{
  "token": {
      "brandLogoUrl": "https://preset-assets-production.s3.us-west-2.amazonaws.com/logo_p.png",
      "brandLogoAlt": "Company Logo",
      "brandLogoHref": "https://manage.app.preset.io",
      "brandLogoHeight": "42px",
      "brandLogoMargin": "4px 8px 4px 16px",
      "brandIconMaxWidth": "150px"
  }
}

Note: Logos customized in themes will override any team logo that you had previously set.

Custom Spinner:

json
{
  "token": {
      "brandSpinnerUrl": "https://example.com/spinner.gif",
      "brandSpinnerSvg": "https://example.com/spinner.svg"
      }
}

Custom Fonts:
Coming soon!

Step 3: Test Your Theme

Before applying a theme workspace-wide, you can preview it locally:

1. From the Theme Creation Modal: Click the ⚡ Apply button to test the theme
   

2. From the Themes Page: Hover over any theme and click the ⚡ icon

This applies the theme just for you, not for other users in the workspace. To remove the test theme, use the theme picker in the top right corner and select Clear local theme.

Setting Workspace Themes

System Default Theme

Click the sun icon (☀️) on any theme to set it as the workspace-wide default theme. This theme will be applied to all users who haven't selected a different theme.

System Dark Theme

Click the moon icon (🌙) on any theme to set it as the workspace dark mode theme. This theme will be applied to all users who are using the Preset workspace in dark mode.

Managing Workspace Level Themes

• Default and dark modes set by the Workspace Admin are indicated with badges in the theme list.
• System themes created by Preset are also indicated with special badges in the theme list. These themes can be viewed but not edited, and will be the fallback theme in rare cases where custom themes can't be loaded.
• Only one default theme and one dark theme can be active at a time

User Light and Dark Theme Selection

Users can control their individual theme preference using the theme picker in the top right corner. Users have three options:

• Light: Always use the workspace default (light) theme
• Dark: Always use the workspace dark theme
• Match System: Automatically switch between light and dark themes based on their system preferences

This allows each user to customize their viewing experience while maintaining consistent branding across the workspace.

Applying Themes to Dashboards

Once created, themes can be applied to individual dashboards for branded or context-specific styling:

1. Navigate to your dashboard and click Edit dashboard
2. Click the ... menu in the top right corner
3. Select Edit properties
4. Expand the Styling section
5. Choose your custom theme from the Theme dropdown
6. Click Save to apply the changes

Note: Dashboard themes only affect the dashboard view, not the Preset UI navigation or other interface elements.

Customizing Chart Visualizations

You can customize the appearance of ECharts-based visualizations (listed below) directly in your theme configuration. This applies your styling to all charts of that type, so you don't need to modify each chart individually.

Global Chart Overrides

Apply settings to all ECharts visualizations by adding echartsOptionsOverrides to your theme. For example:

{
  "token": {
    "colorPrimary": "#2893B3"
  },
  "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, as in the example below:

{
  "token": {
    "colorPrimary": "#2893B3"
  },
  "echartsOptionsOverridesByChartType": {
    "echarts_pie": {
      "legend": {
        "orient": "vertical",
        "right": 10,
        "top": "center"
      }
    },
    "echarts_timeseries_line": {
      "xAxis": {
        "axisLabel": {
          "rotate": 45,
          "fontSize": 12
        }
      }
    },
    "echarts_bubble": {
      "grid": {
        "left": "15%",
        "bottom": "20%"
      }
    }
  }
}

When global ECharts overrides and chart specific overrides are defined, the chart specific overrides will take precedence.

The following charts support chart-specific overrides:

Support for additional echarts customizations is coming soon!

Import & Export of Themes

To share a theme with another workspace or export it for backup:

1. Navigate to Settings > Themes
2. Click the export icon on the theme you want to copy
3. A YAML file will be downloaded
4. Extract the JSON configuration from the YAML file
5. Import it into your target workspace by clicking the import button on the Themes page

Dashboard CSS (Legacy Method for Customization)

While themes are the recommended approach, you can still use CSS for dashboard customization. However, CSS is more brittle and may break with future updates.

If you have CSS applied to a dashboard, it will override the theme configuration for that dashboard. For more information on using CSS with theming, see CSS and Theming.

Theming for Embedded Dashboards

Embedded dashboards in Preset support dynamic theme configuration, allowing host applications to control the appearance of embedded content.

Configuring Embedded Themes

When embedding a dashboard, you can specify theme configurations in the embedded SDK. For example:

embedDashboard({
  id: "dashboard-id",
  supersetDomain: "https://your-workspace.preset.io",
  mountPoint: document.getElementById("dashboard"),
  fetchGuestToken: () => fetchToken(),
  dashboardUiConfig: {
    theme_default: {
      token: {
        colorPrimary: "#2893B3",
        fontFamily: "Inter, sans-serif"
      }
    },
    theme_dark: {
      algorithm: "dark",
      token: {
        colorPrimary: "#2893B3"
      }
    }
  }
});

Dynamic Theme Switching

The embedded SDK provides a setThemeMode() method for dynamic theme switching between light and dark modes:

// Switch to dark theme
dashboard.setThemeMode('dark');

// Switch to default theme
dashboard.setThemeMode('default');

// Use system preference
dashboard.setThemeMode('system');

Note: The setThemeMode() method only works when both theme_default and theme_dark are configured.

Best Practices

Theme Design

1. Start with global Echart overrides for consistent styling across all charts
2. Use chart-specific overrides only when a visualization type requires unique styling
3. Test in both light and dark modes before setting a theme as your default light or dark theme. Use the "Set local theme" option to test.
4. Document your customizations to help team members understand your theme choices

Creating Dark Mode Themes

To design themes that work well in both light and dark modes:

• Use contrasting bold colors that maintain visibility in both modes
• Avoid pure black (#000000) and pure white (#FFFFFF) - use slightly softer shades for better readability
• Test iteratively using the Ant Design Theme Editor's preview feature
• Consider accessible contrast ratios (WCAG AA standard recommends 4.5:1 for normal text)
• Use the theme editor's algorithm property - set to "dark" for dark themes to automatically adjust component colors

Example dark theme configuration:

{
  "algorithm": "dark",
  "token": {
    "colorPrimary": "#1890ff",
    "colorBgBase": "#141414",
    "colorTextBase": "#e8e8e8"
  }
}

API Access

For programmatic theme management, Preset 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 role-based access controls (RBAC).