Skip to main content

Coloring/theming

Set colors and sizing under a top-level theme in the configuration section. JBrowse's palette has four customizable colors (primary, secondary, tertiary, quaternary), and a dark block for whatever a palette wants different when drawn dark. configuration.preferences sets the starting value of the settings users can toggle for themselves.

Color

theme takes a MUI palette plus typography and spacing. tertiary and quaternary are JBrowse extensions to the standard MUI palette, which has only primary and secondary:

{
  "configuration": {
    "theme": {
      "palette": {
        "primary": { "main": "#311b92" },
        "secondary": { "main": "#0097a7" },
        "tertiary": { "main": "#f57c00" },
        "quaternary": { "main": "#d50000" }
      },
      "typography": { "fontSize": 10 },
      "spacing": 2
    }
  }
}
Example screenshot showing the default theme
Open in JBrowse Web ↗Open in JBrowse Desktop ↗
Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

https://jbrowse.org/code/jb2/main/?config=test_data%2Fvolvox%2Fconfig_theme_default.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22volvox%22%2C%22loc%22%3A%22ctgA%3A1-50000%22%7D%5D%7D&sessionName=JBrowse+docs%3A+default_theme

Or rebuild it from your own data:

The short route: open the view in JBrowse Web, where File → Open track... adds your own files beside its hosted genome and tracks.

From scratch with your own data, the steps behind the figure:

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses volvox, loaded from a .2bit genome.
  2. Type your region of interest into the location box and press Enter.This figure is at ctgA:1-50000.

This session spec draws the figure. It goes after &session=spec- on a JBrowse Web link that loads https://jbrowse.org/code/jb2/main/test_data/volvox/config_theme_default.json, which is what the Web button above opens.

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "volvox",
      "loc": "ctgA:1-50000"
    }
  ]
}

The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own file.

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/code/jb2/main/test_data/volvox/config_theme_default.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "volvox",
            "loc": "ctgA:1-50000"
        }
    ],
)
app  # display the widget

jbrowse-img draws the same view as an SVG, from the command line and without a browser. Point --config at your own config, or swap a track for your own file with --bam, --vcfgz and the other file flags.

npx @jbrowse/img --config https://jbrowse.org/code/jb2/main/test_data/volvox/config_theme_default.json \
  --assembly volvox --loc ctgA:1-50000 \
  --width 1500 --out figure.svg

--out figure.png writes a PNG instead, through rsvg-convert (apt install librsvg2-bin, brew install librsvg).

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit: change the location or a track's settings, or add your own track under sessionTracks, and rerun.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "volvox",
      "loc": "ctgA:1-50000"
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/volvox/config_theme_default.json \
  --width 1500 --height 520 \
  --spec session.json -o figure.png

The figure was taken after clicks this command does not make, so its picture can differ.

Using JBrowse with AI agents covers the rest: hosted genomes to point it at, and why waiting for the render is the part that goes wrong.

Example screenshot showing the customized theme
Open in JBrowse Web ↗Open in JBrowse Desktop ↗
Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

https://jbrowse.org/code/jb2/main/?config=test_data%2Fvolvox%2Fconfig_theme_custom.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22volvox%22%2C%22loc%22%3A%22ctgA%3A1-50000%22%7D%5D%7D&sessionName=JBrowse+docs%3A+customized_theme

Or rebuild it from your own data:

The short route: open the view in JBrowse Web, where File → Open track... adds your own files beside its hosted genome and tracks.

From scratch with your own data, the steps behind the figure:

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses volvox, loaded from a .2bit genome.
  2. Type your region of interest into the location box and press Enter.This figure is at ctgA:1-50000.

This session spec draws the figure. It goes after &session=spec- on a JBrowse Web link that loads https://jbrowse.org/code/jb2/main/test_data/volvox/config_theme_custom.json, which is what the Web button above opens.

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "volvox",
      "loc": "ctgA:1-50000"
    }
  ]
}

The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own file.

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/code/jb2/main/test_data/volvox/config_theme_custom.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "volvox",
            "loc": "ctgA:1-50000"
        }
    ],
)
app  # display the widget

jbrowse-img draws the same view as an SVG, from the command line and without a browser. Point --config at your own config, or swap a track for your own file with --bam, --vcfgz and the other file flags.

npx @jbrowse/img --config https://jbrowse.org/code/jb2/main/test_data/volvox/config_theme_custom.json \
  --assembly volvox --loc ctgA:1-50000 \
  --width 1500 --out figure.svg

--out figure.png writes a PNG instead, through rsvg-convert (apt install librsvg2-bin, brew install librsvg).

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit: change the location or a track's settings, or add your own track under sessionTracks, and rerun.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "volvox",
      "loc": "ctgA:1-50000"
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/volvox/config_theme_custom.json \
  --width 1500 --height 520 \
  --spec session.json -o figure.png

The figure was taken after clicks this command does not make, so its picture can differ.

Using JBrowse with AI agents covers the rest: hosted genomes to point it at, and why waiting for the render is the part that goes wrong.

Light and dark

A palette and its light/dark setting are two separate things in Preferences. The theme picker chooses colors — Default (from config), Stock, Minimal, or any extraThemes entry — and a second control chooses Light, Dark or Follow system. Moving one leaves the other alone, so a reader on Minimal who switches to dark gets dark Minimal, and the colors you set under theme above apply in both.

Sessions start on Light, so a reader reaches dark by asking for it. Picking Follow system puts a sun or moon in the toolbar naming the mode the OS landed on. Clicking it switches to the other mode and holds it until the OS next changes; clicking again goes back to following.

Most of a dark theme follows from the setting: the backgrounds, text, dividers, gridlines, coverage and hover colors all have dark values already. What does not survive the flip is a brand color — a deep navy that reads well on white is nearly invisible on a dark background — so a palette may state the slots it wants different when drawn dark:

{
  "configuration": {
    "extraThemes": {
      "myTheme": {
        "name": "My theme",
        "palette": {
          "primary": { "main": "#311b92" },
          "dark": { "primary": { "main": "#9a86e0" } }
        }
      }
    }
  }
}

State "mode": "dark" in a palette instead and it is a dark-only theme: the light/dark control no longer applies to it, because the light colors were never written. In the top-level theme the same key is the instance's starting mode, which a reader's own choice overrides.

Extra themes

extraThemes entries join Stock and Minimal in the Preferences theme picker, each with the same palette keys as the top-level theme above. name is the row the user sees:

{
  "configuration": {
    "extraThemes": {
      "myTheme": {
        "name": "My theme",
        "palette": { "primary": { "main": "#311b92" } }
      }
    }
  }
}

logoPath replaces the JBrowse 2 logo in the top right corner with an SVG from your server:

{
  "configuration": {
    "logoPath": { "uri": "path/to/my/custom-logo.svg" }
  }
}

The logo fills the toolbar height and keeps its aspect ratio up to 150px wide, so a wide, short logo (roughly 3:1) fills the space best.

User preference defaults

configuration.preferences sets the starting value of each setting in the Preferences dialog. A user's own choice is stored in localStorage and wins from then on, so these are defaults for your instance, not a lock:

{
  "configuration": {
    "preferences": {
      "numberGrouping": false,
      "scrollZoom": true,
      "animationMode": "system"
    }
  }
}

PreferencesConfigSchema lists each slot.

Advanced

JBrowse themes through Material-UI, so most createTheme options work in the config. Style overrides that need callback functions come from a plugin instead; the volvox umd_plugin.js adds a theme that way, and the no-build plugin guide shows how to load one.

See also