Skip to main content

Coloring/theming

TL;DR: set colors and sizing under a top-level theme in the configuration section. JBrowse's palette has four customizable colors (primary, secondary, tertiary, quaternary); add "mode": "dark" inside a palette for dark mode. 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 this view in JBrowse ↗

The steps behind the figure above, run against your own data.

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one).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.

Open this view in JBrowse Desktop ↗

Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session — swap in your own files afterwards.

Nothing happens? 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

This session spec pastes after &session=spec- on any JBrowse Web instance.

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

Loaded against config: test_data/volvox/config_theme_default.json

The same view with jbrowse-anywidget. Point the adapter at your own file.

from jbrowse_anywidget import LinearGenomeView, make_assembly

view = LinearGenomeView(
    assembly=make_assembly("volvox", "https://your-server/your-genome.fa.gz"),
    location="ctgA:1-50000",
)

view  # display the widget

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit — swap an adapter uri for your own file 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 \
  --session session.json -o figure.png

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 this view in JBrowse ↗

The steps behind the figure above, run against your own data.

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one).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.

Open this view in JBrowse Desktop ↗

Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session — swap in your own files afterwards.

Nothing happens? 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

This session spec pastes after &session=spec- on any JBrowse Web instance.

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

Loaded against config: test_data/volvox/config_theme_custom.json

The same view with jbrowse-anywidget. Point the adapter at your own file.

from jbrowse_anywidget import LinearGenomeView, make_assembly

view = LinearGenomeView(
    assembly=make_assembly("volvox", "https://your-server/your-genome.fa.gz"),
    location="ctgA:1-50000",
)

view  # display the widget

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit — swap an adapter uri for your own file 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 \
  --session session.json -o figure.png

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.

Extra themes and dark mode

extraThemes entries show up in the Preferences dialog for the user to select. "mode": "dark" inside any palette switches it to MUI's dark mode, on the top-level theme too:

{
  "configuration": {
    "extraThemes": {
      "myTheme": {
        "name": "My theme",
        "palette": {
          "mode": "dark",
          "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,
      "useWorkspaces": true,
      "animationMode": "system"
    }
  }
}

PreferencesConfigSchema lists each slot. A session that names useWorkspaces itself still wins over the preference.

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