Create custom themes
This guide shows you how to create a custom theme for the Deephaven web UI. Themes work by providing a set of CSS variables that override either the default dark or light theme.
As a worked example, this guide walks through a theme that emulates the look of the Financial Times website. You start from its files and change them into your own theme. You package a theme as a JS plugin, which extends the Deephaven web UI, and install it on your server.

Tip
If you want ready-made themes rather than your own, install the theme pack plugin by packaging its @deephaven/js-plugin-theme-pack npm package, as shown in Install the theme pack. It includes the Financial Times theme this guide walks through, along with several others.
Development setup
To design and preview your theme, you run three things side by side: a Deephaven server, a plugin development server that serves your theme plugin, and a development build of the Deephaven web UI. This setup is for development only. When your theme is complete, follow Build and deploy your theme to install it on your server.
You also need Node.js and npm at the versions each repository requires. Both repositories refuse to install on other versions. Each lists its Node.js version in its .nvmrc file, which nvm use reads.
Set up the three pieces in order. In step 2, you create your theme plugin by copying the theme pack:
-
A Deephaven server.
- Start a Deephaven server on port
10000. Follow the Quickstart.
- Start a Deephaven server on port
-
Your theme plugin and a plugin development server. The development server builds your plugins whenever you save a change and serves them to the web UI, so you can iterate quickly without reinstalling the plugin after every change. The plugin development server listens on port
4100.-
Clone the deephaven-plugins project.
-
Copy the
plugins/theme-packdirectory to a new directory underplugins/, named for your plugin, such asplugins/my-theme. -
In
plugins/<your-theme>/src/js/package.jsonandplugins/<your-theme>/src/js/src/index.ts, rename thetheme-packreferences to your plugin name. -
In
package.json, also change the package name from the@deephavenscope to your own, such as@my-org/my-theme. -
In
plugins/<your-theme>/src/js/src/index.ts, keep theFT Themeentry in thethemeslist. It loadstheme.css, the Financial Times example theme this guide walks through. The copied file imports the stylesheet asftStyleContent. The minimal version in Inherit a base theme calls itstyleContent. Either name works. -
Delete the other themes' entries and imports from
index.ts, and delete their.cssfiles. -
Set the
namekey of the remaining entry to a unique name. This name appears in the theme selector in the Deephaven web UI. -
Add an entry for your plugin to the
plugins/manifest.jsonfile to enable your plugin in development previews. Copy thetheme-packentry and change itsnameto your plugin name. -
Open a terminal other than the one running your Deephaven server. From the root directory of your deephaven-plugins clone, run:
npm startrebuilds every plugin in the repository when you save. To rebuild only your theme plugin, pass its package name with--scope, for examplenpm start -- --scope @my-org/my-theme.
-
-
A development build of the Deephaven web UI, built from the web-client-ui repository.
-
Clone the deephaven/web-client-ui repository.
-
In web-client-ui, create the file
./packages/code-studio/.env.development.localif it doesn't already exist, and add the following line so the web UI loads plugins from the plugin development server on port4100: -
Open a new terminal. From the root directory of your web-client-ui clone, run:
-
The web UI development build runs at http://localhost:4000/ide/ and connects to the Deephaven server on port 10000. Visit it and, if prompted, log in with the pre-shared key printed in the server log. To preview your theme, open the Settings menu and select it from the Pick a color scheme list in the Theme section:

Alternatively, visit http://localhost:4000/ide/styleguide for a preview of all the components in the web-client-ui library. To change the theme, click the theme selector in the top-right corner of the style guide:

Note
If you change your styles, refresh the page to see the changes.
Theme file overview
You define your theme's styles in plugins/<your-theme>/src/js/src/theme.css. The file you copied contains the Financial Times example theme.
The file sets CSS variables on :root. They override the same variables in the base theme, the default dark or light theme that your theme inherits. Inherit a base theme shows how to choose it.
Override only the variables you want to change. Every other variable keeps its base-theme value. Most themes start by overriding a few colors and add more variables as needed.
See the entire example theme.css file.
The web-client-ui repository lists the theme variables you can override in the Default Dark and Default Light themes, organized into files by usage. You can also inspect elements in the browser to find the variable a component uses. To override a component's class directly, see Override individual components with CSS selectors, which also explains why we don't recommend this approach.
Create your theme
To create a theme:
- Inherit a base theme (
darkorlight). - Use color generators and define your palette (gray, red, orange, etc.).
- Use your palette for semantic colors (accent, positive, negative, etc.).
- Use your palette for component-specific semantic colors (grid, plot, etc.).
The sections below show how we built the example theme. It inherits the light base theme in index.ts. Then, in theme.css, it defines gray, red, green, and seafoam palettes, points the accent colors at seafoam, and overrides a few grid and plot colors.
Inherit a base theme
To create your theme, first decide whether your theme is light or dark. For example, if your desired background color is black or purple, inherit dark. If it's white or yellow, inherit light. Inheriting from either dark or light significantly reduces the amount of work required to create a custom theme.
In the plugins/<your-theme>/src/js/src/index.ts file, set the baseTheme of your theme to either dark or light. The theme's name is the name that appears in the theme selector, and styleContent holds the contents of your theme.css file:
Use color generators and define your palette
The Deephaven design system is based on the Adobe Spectrum color system. It uses a palette that consists of:
- 11 shades (50, 75, and 100-900) of a
graypalette used for background colors - 14 shades (100-1400) of each of 13 hues:
red,orange,yellow,chartreuse,celery,green,seafoam,cyan,blue,indigo,purple,fuchsia, andmagenta
The shades of every palette, gray and the 13 hues alike, range from light to dark for light themes and from dark to light for dark themes.
The gray shades aren't evenly spaced. In the light example theme, shades 50, 75, and 100 are close together in lightness, and shades 100 through 900 are spaced further apart. In the default dark palette, shades 50 through 400 are close together, and the large steps start at 500. Compare your shades with your base theme's palette file, theme-light-palette.css or theme-dark-palette.css. The full palette of the example theme shows this spacing:

We recommend generating a palette with Adobe's Leonardo color tool. Leonardo is a great tool for building color ramps, the ordered series of shades for one color. Its Export as CSS feature gives the hex value of each shade. Coolors also works. If your company has a brand guide with full palettes, you can use those instead.
Note
Colors must be in the sRGB color space. Here we use HSL values, but you can use any supported color format. Supported formats include #hex, rgb(), rgba(), hsl(), hwb(), color(srgb ...), and named colors. Other color spaces, such as LAB, OKLAB, and P3, are not supported.
The web UI converts your colors to hex, because some components read colors in JavaScript rather than CSS:
- Canvas-based grids.
- Monaco code editors.
- SVG and WebGL plots.
The conversion handles only sRGB colors, which is why other color spaces aren't supported. The default themes also derive transparent variants of your palette colors with color-mix in the sRGB color space.
To build the example theme, we picked a background color inspired by the Financial Times site and generated shades from it in Leonardo. The palette is named gray, but it can be any background color. The resulting gray background palette, which goes inside the :root block of theme.css, is:
We also override the red, green, and seafoam palettes with colors inspired by the Financial Times site. Their values are in the example theme.css file.
Use your palette for semantic colors
Semantic colors are variables named for the role a color plays rather than its hue. For example, accent sets the color of buttons and other highlighted controls, and positive and negative set the colors of gains and losses. Each semantic variable points at a palette color, so changing the palette changes every semantic color built on it.
Depending on how much you want to customize, you can stop after setting the palette and inherit the rest of the theme from the base theme. You can also override more variables to customize the theme further. For example, this guide's theme changes the accent variables from blue to seafoam. Like the palette, these declarations go inside the :root block:
positive defaults to green, and negative defaults to red. Updating the green and red palettes changes these variables. You can also change them independently if you want a different color for positive or negative values or actions.
For the full list of semantic variables, see the files with semantic in their names, such as theme-light-semantic.css, in the Default Dark and Default Light themes.
Use your palette for component-specific semantic colors
Component-specific semantic colors are variables that apply to a single component, such as the grid header background or the chart colorway. The colorway is the ordered list of colors a chart assigns to its series. Override these variables when the palette and semantic colors don't give you the look you want in a specific component.
The example theme overrides these component variables:
- The grid header and row stripe colors. Only the even-row stripe differs from the light theme's default.
- The grid's date color.
- The chart colorway.
These declarations also go inside the :root block. The overrides refer to variables that the base theme already defines, so you don't define them yourself. --dh-color-black and --dh-color-white map to shades of the gray palette. The semantic files linked in Use your palette for semantic colors define --dh-color-accent-bg and the --dh-color-visual-* data-visualization colors.
Override individual components with CSS selectors
You can also override specific components with CSS selectors that set your own variables and properties, as the .console-input-wrapper rule at the end of the example theme.css file does.
Caution
We don't recommend overriding components this way, because class names and DOM structure can change in future web-client-ui releases. If you need a variable that the default themes don't expose, open a web-client-ui GitHub issue or ask in the #web-client-ui channel of the Deephaven Community Slack.
Build and deploy your theme
The development servers only preview your theme. To use it on a Deephaven server, build the plugin and install it on that server:
-
Build the plugin. From the
plugins/<your-theme>/src/jsdirectory of your deephaven-plugins clone, run: -
Install the plugin on your server as a JS-only plugin. The server registers plugins from Python packages only when Python is its script language. On a Groovy server, the Python packaging in the
theme-packdirectory you copied doesn't apply.To package the plugin, use a Dockerfile build stage based on the
ghcr.io/deephaven/web-plugin-packagerimage:- Copy your built
plugins/<your-theme>/src/jsdirectory into the stage at an absolute path, for exampleCOPY my-theme/src/js /my-theme. - Run the packaging script on that directory, for example
RUN ./pack-plugins.sh /my-theme. Pass an absolute path, because the script runsnpm packfrom a temporary subdirectory, where a relative path such as./my-themedoesn't resolve. - Copy the
js-pluginsdirectory that the script generates to thejs-pluginsdirectory in your server's configuration directory (<configDir>/js-plugins/).
For details, see Configure JS plugins.
For other ways to register a JS plugin, such as pointing the server at the plugin's npm package directory during development, see Create a JavaScript plugin.
- Copy your built
-
Restart the server, then select your theme in the Settings menu.