Theming

TL;DR: JBrowse extends MUI theming with custom palette properties, set via the configuration.theme field. For an end-user walkthrough of colors, dark mode, the logo, and sizing, see the Coloring/theming config guide.

Built-in themes#

Set configuration.theme to one of these names:

• default - uses config-supplied colors merged with stock defaults
• lightStock - light mode with stock JBrowse palette
• lightMinimal - light mode with greyscale chrome
• darkStock - dark mode with stock palette
• darkMinimal - dark mode with greyscale chrome

Custom palette properties#

These extend MUI's standard primary/secondary/error/etc. Every key below is optional in a config theme; anything you don't set keeps its preset value.

The frames / framesCDS tuples are indexed by reading frame — 1/2/3 forward and -1/-2/-3 reverse, which is why slot 0 is unused.

Defaults for the string-valued feature colors, generated from the #color-tagged definitions in packages/core/src/ui/palette.ts (the insertion/softclip/hardclip indicators are tagged under a separate alignments-indicators group):

Exported color constants#

A few colors are plain const strings rather than palette members. The methylation colors are the worked case: the RPC worker packs them to ABGR per modified base and returns them inside its vertex data, and the legend on the main thread labels those same pixels.

Where the color is applied is what decides which mechanism it uses. modificationFwd and modificationRev sit right beside these and are palette members, because the renderer sets them as shader uniforms, so a theme switch recomputes a getter and redraws. A color the worker has already baked into vertex data would need a theme switch to invalidate the alignments fetch, so it is fixed instead.

Import them from @jbrowse/core/ui/palette, which has no toolkit in its module graph, or from @jbrowse/core/ui/theme, which re-exports the same values alongside Material UI.

The palette carries no such key, so the worker, the legend and an SVG export all read the same constant.

Example config#

{
  "configuration": {
    "theme": {
      "palette": {
        "primary": { "main": "#311b92" },
        "secondary": { "main": "#0097a7" },
        "tertiary": { "main": "#f57c00" },
        "quaternary": { "main": "#d4ac0d" }
      }
    }
  }
}

primary/secondary/tertiary/quaternary/highlight accept either a full MUI PaletteColorOptions object or just { "main": "<hex>" }. Light/dark variants are derived automatically.

Reading colors from a display#

session.palette and session.theme are both on the session and both resolve from the same resolvePalette call, so they can't disagree. They are for different consumers, and one of them is the rendering input:

• session.palette (JBrowsePalette) is what rendering reads. Plain color strings, no toolkit, serializable — so it crosses the RPC boundary as itself and works with no browser at all.
• session.theme is the resolved MUI Theme, for components that are MUI.

Derive a display's colors in a model getter over session.palette, and read that getter from renderState or whatever you hand the renderer. MAF's is the worked case:

get colorPalette(): MafColorPalette {
  return getMafColorPalette(getPaletteHost(self).palette)
},

Do not stage them in a volatile that a React useEffect pushes in with a setColorPalette action. The effect only runs on mount, and two consumers have no component at all — SVG export and the RPC worker — so both would see a null palette and render blank. As a getter the value is always present, and MobX recomputes it only when the theme changes.

SVG export deliberately overrides the palette with the export theme, which is why the export path resolves its own rather than reading the session's.

Adding theme colors in plugins#

Colors the main thread applies, whether in a React component or as a shader uniform the renderer sets, belong in the Palette / PaletteOptions module augmentation. Follow the existing modificationFwd / modificationRev pattern:

• Declare the field on StringColors in palette.ts.
• Tag it with #color <group> | <label> | <description> so it surfaces as a swatch row in these guides.
• Give it a value in lightStringColors, plus darkStringColors if dark mode needs a different one — a Partial<StringColors> overlay on the light set rather than a second full table.

A color a worker bakes into its output goes the other way: declare it as a plain const in palette.ts and leave it off StringColors, for the reason in Exported color constants. Worker code imports those from @jbrowse/core/ui/palette, which keeps Material UI out of its bundle.

See also#

• Config guide: coloring/theming
• Writing a plugin