URL query parameter API

JBrowse Web supports URL parameters for initializing a session.

For embedded components like @jbrowse/react-linear-genome-view2, the consuming application implements URL parameter handling itself.

Query string or hash fragment

Every parameter on this page works in either place: ?config=…&loc=… or #config=…&loc=…. A fragment is never sent to the server, so a long value — an encoded-/json- session, a whole session spec, a big &sessionTracks= — cannot trip the request-line limit that answers a long query string with HTTP 414. That is why the Share button writes its two inline formats as hash URLs.

If the fragment contains an =, JBrowse reads its parameters only from there and ignores the query string, so moving one long parameter into the fragment means moving them all: ?config=my.json#session=spec-{…} loads the default config.json, not my.json.

Linear genome view (simple)

A simplified URL format for launching a single linear genome view:

http://host/jbrowse2/?config=test_data/config.json&loc=chr1:6000-7000&assembly=hg19&tracks=gene_track,vcf_track

&assembly=, &loc=, &regions=, &nav=, &tracks=, &tracklist=, &highlight=, &sessionTracks= and &extendSession= apply only to this single linear genome view launch — every other launch type carries the same settings inside the session it loads. ?config=, &sessionName=, &hubURL=, &renderer= and &session= work for any launch type.

Two more are documented with the feature they belong to: &password= with &session=share-, and &adminKey= in JBrowse CLI admin server.

?config=

?config=test_data/volvox/config.json

A path to a JBrowse 2 config file, relative to the current folder on disk, fetched by the client. If ?config= is omitted, JBrowse looks for config.json in the current folder (e.g. http://host/jbrowse2/config.json), which is what the @jbrowse/cli tool sets up by default.

The special value ?config=none skips loading a config file entirely. This is useful with &hubURL= (below), which supplies its own assemblies and tracks.

To change the default without putting ?config= in every link, set window.__jbrowseConfigPath in the <head> of JBrowse's index.html — see Avoiding stale config, which uses the same mechanism. An explicit ?config= still wins over it.

&assembly=

&assembly=hg19

&assembly= refers to the name field of an entry in the assemblies array of config.json.

&loc=

&loc=chr1:6000-7000

Navigates to this region on load. Accepts the formats shown below.

Example strings

&loc=chr1:6000-7000 // using - notation for range
&loc=chr1:6000..7000 // using .. notation for range
&loc=chr1:7000 // centered on this position
&loc=chr1 // the whole of one chromosome
&loc=chr1%206000%207000 // refName, start and end, whitespace separated
&loc=chr1:34M-35M // coordinates abbreviated with a unit suffix
&loc=GENEID // if you have used `jbrowse text-index`

A coordinate may be written with a k, M or G suffix, optionally followed by b or bp, so chr1:34M-35M, chr1:1.5Mb-2Mb and chr1:500kb-600kb are all accepted. These are expanded to whole base pairs on load, and the location box then reads back the full number.

Navigating via &loc=GENEID requires a text index built with jbrowse text-index.

Several whitespace-separated locstrings open a discontinuous view showing each region in turn — a gene and the partner it is fused to, an allele beside the sequences it derives from. The space is URL-encoded as %20:

&loc=chr3:25,325,000-25,361,000%20chr10:58,716,500-58,718,500

This is the same form the location box displays once a view holds more than one region, so what you copy out of it pastes back into a URL. To open a whole-genome view restricted to particular chromosomes instead, use &regions=.

By default &loc= (and &assembly=) start a fresh session, ignoring the config's defaultSession; &extendSession=true navigates that session instead of replacing it.

&regions=

&assembly=hg38&regions=chr1,chr2,chr3

Restricts the whole-genome overview to this comma-separated subset of the assembly's chromosomes, in the order given, handy for dropping unplaced/alt contigs or reordering. Names resolve through the assembly's aliases. It is ignored when &loc= is set, and it requires &assembly=. This is the simple-URL form of the session-spec displayedRegionNames field, and takes the same globs.

&highlight=

&highlight=chr1:6000-7000

Creates a highlight over the specified region when combined with &assembly= and &loc=.

Multiple highlight locations can be specified by delimiting locations with a space (URL-encoded as %20):

&highlight=chr1:6000-7000%20chr1:7100-7200

Always pass &assembly= alongside &highlight=. Highlights are stored by assembly name so downstream features (e.g. bookmarking from the chip menu) can resolve them. Without one, a highlight still renders when its refName matches a displayed region, but it is not portable across assemblies and may break actions that need a fully-qualified region. The same applies to view.highlight in a session JSON: include assemblyName on each entry.

view.highlight entries also accept optional color and label fields, both when authoring a session JSON directly and via the URL by passing a JSON object (URL-encoded) instead of a loc string:

{
  "refName": "11",
  "start": 32200274,
  "end": 32203877,
  "assemblyName": "mm39",
  "color": "rgba(240, 128, 128, 0.3)",
  "label": "R2_intron"
}

color overrides the theme highlight color, used as-is, so explicit alpha is preserved
label is shown inline next to the chip icon and in the chip tooltip

URL form (URL-encode the JSON):

&highlight={"refName":"11","start":32200274,"end":32203877,"color":"rgba(240,128,128,0.3)","label":"R2_intron"}

JSON highlights use the same %20 space delimiter, and loc strings and JSON objects can be mixed in one &highlight= value.

This highlights a region, over every track at once, and needs coordinates. To box a single feature by name, and sort it to the top of its track's layout, see featureHighlights.

&tracklist=

&tracklist=true

Opens the track selector on load. Default: false.

&nav=

&nav=false

Turns off the navigation bar of the linear genome view. Default true.

&tracks=

&tracks=gene_track,vcf_track

A comma-separated list of trackIds, which the config.json defines. A trackId added by &sessionTracks= can be named here too.

&sessionTracks=

&sessionTracks= dynamically adds a track to the session. It can also add a FromConfigAdapter track, specifying features inline as JSON — BLAST hits from the URL bar, say.

A track over a data file needs no type or adapter — the extension gives both:

&sessionTracks=[{"trackId":"reads","uri":"https://example.com/sample.bam","assemblyNames":["hg38"]}]

Nothing implies the assembly for a session track, so name it — see the shortest track. The full form below is what a track with no data file needs.

https://jbrowse.org/code/jb2/main/?config=test_data/volvox/config.json&loc=ctgA:1-800&assembly=volvox&tracks=gff3tabix_genes,volvox_filtered_vcf,volvox_microarray,volvox_cram,url_track&sessionTracks=[{"type":"FeatureTrack","trackId":"url_track","name":"URL track","assemblyNames":["volvox"],"adapter":{"type":"FromConfigAdapter","features":[{"uniqueId":"one","refName":"ctgA","start":100,"end":200,"name":"Boris"}]}}]

Live link

This creates a track with a single feature at ctgA:100-200.

The value is an array of track configs. Pretty-printed, the one above is:

[
  {
    "type": "FeatureTrack",
    "trackId": "url_track",
    "name": "URL track",
    "assemblyNames": ["volvox"],
    "adapter": {
      "type": "FromConfigAdapter",
      "features": [
        {
          "uniqueId": "one",
          "refName": "ctgA",
          "start": 100,
          "end": 200,
          "name": "Boris"
        }
      ]
    }
  }
]

&sessionName=

&sessionName=My%20Custom%20Session

Sets the session name displayed in the header bar. It works with all session types:

Default sessions (loaded from config)
Session specs (&session=spec-...)
Hub sessions (&hubURL=...)

Use it to give URL-launched sessions a meaningful name; without it the name is auto-generated with a timestamp. URL-encode the value if it contains spaces or special characters.

&hubURL=

&hubURL=https://example.com/hub.txt&config=none

Loads one or more UCSC track hubs as a session (multiple hubs as a comma-separated list), typically combined with ?config=none since the hub supplies its own assemblies and tracks.

Add &loc= and &assembly= to open the hub at a particular place. &assembly= is required for this: it names the hub genome that &loc= resolves against.

?config=none&hubURL=https://example.com/hub.txt&assembly=GCF_019202715.1&loc=chr1:1-100000

&sessionTracks= works alongside a hub, registering its track configs into the hub session, so &tracks= can name one of them beside the hub's own tracks.

&hubURL= opens each hub with a single linear genome view. For anything beyond that — several views over a hub, a workspace layout, or a dotplot — put the hub in a session spec's sessionConnections instead.

See Opening track hubs by URL for the full workflow, including combining a hub with a config and loading several at once.

&renderer=

&renderer=webgl

Pins the backend tracks are drawn with, overriding automatic detection. Each value pins one backend:

webgpu requires WebGPU
webgl skips WebGPU and uses WebGL2
canvas2d skips both and draws in software. canvas is accepted as an alias for it

A pin never falls through to the next backend: if the one you named cannot start, tracks show an error saying so. Any other value is ignored, with a console warning naming the ones that work.

It is a debugging aid: trying each in turn says whether a blank or wrong-looking track comes from the GPU path, see my tracks are blank or render incorrectly. JBrowse Desktop takes the same choice as a --renderer command-line flag, see JBrowse desktop quick start.

&safeMode

&safeMode

Loads without the plugins this browser keeps for this configuration, see keeping a plugin for every visit. The list is left alone — the plugins are skipped for this load only, and the next one without the parameter runs them again.

Its own use is a plugin that crashes the app before any menu is on screen. The fatal error dialog offers the same thing as a button, and JBrowse turns them off by itself after a load that never finished; the parameter is for the case where neither has happened and you want to rule them out.

Bare, with no value, is how it is normally written. &safeMode=1 works too: what counts is that the parameter is present.

Navigating within the default session

&extendSession=true alongside &loc= navigates a curated defaultSession while keeping its tracks and settings, rather than replacing it:

?loc=chr1:100000-200000&extendSession=true

&loc=, &tracks=, &highlight=, &nav= and &tracklist= are then applied to the first linear genome view of that defaultSession. The assembly comes from that view, so &assembly= isn't needed. &sessionTracks= is not layered on; a full session spec is the way to add a track config to a curated session.

Which parameter decides the launch

A link can carry several of these at once, and they don't combine — one of them decides what opens and the rest are either layered onto it or dropped. The ranking, highest first:

&session=, in any of its forms (spec-, share-, encoded-, json-, local-). An explicit session always beats a stray &loc=. A value matching none of those prefixes is an error.
&extendSession=true alongside &loc=/&assembly=, which navigates the config's defaultSession — see below. It outranks a hub, which would otherwise replace that session outright.
&hubURL=. A hub brings its own assemblies and tracks, so a link carrying both a hub and &loc= navigates inside the hub: the shorthand rides along on top of the hub session.
&loc=/&assembly= on their own, which build a fresh single linear genome view.
Nothing of the above, which opens the config's defaultSession.

?config=, &sessionName= and &renderer= sit outside the ranking and apply to whichever launch wins. &sessionTracks= applies to the hub launch and to the shorthand on its own. It is not layered onto a default session or onto a &session= of any kind, both of which have their own way to carry a track (a spec's sessionTracks, the snapshot's own).

Session spec

A "session spec" encodes a session as JSON in the URL, as the value of &session=, prefixed spec-:

&session=spec-{"views":[{"type":"LinearGenomeView","assembly":"volvox","loc":"ctgA:1-5100"}]}

Each view object lists the keys that view launches with, flat as below. A spec is arguments to a view's launcher, so nothing is nested. A defaultSession in a config writes the same settings under an init block instead, because there the view is a saved state snapshot (see Config / session files); moving a view between the two means reshaping it, and pasting an init block into a spec is reported. The embedded @jbrowse/react-linear-genome-view2 component takes the init form via defaultSession.view.init.

Under the hood, each view's type dispatches to a LaunchView-<type> extension point that builds the view from the remaining fields. This is also how plugins add launchable view types (see Plugin-provided view types).

{
  "views": [
    {
      "assembly": "volvox",
      "loc": "ctgA:1-5100",
      "type": "LinearGenomeView",
      "tracks": [
        "gff3tabix_genes",
        "volvox_filtered_vcf",
        "volvox_microarray",
        "volvox_cram"
      ]
    }
  ]
}

Property	What it does
`colorByCDS`	color CDS segments by reading frame
`displayedRegions`	currently displayed regions, can be a single chromosome, arbitrary subsections, or the entire set of chromosomes in the genome, but it not advised to use the entire set of chromosomes if your assembly is very fragmented
`displayName`	displayName is displayed in the header of the view, or assembly names being used if none is specified
`hideHeader`	drop the header bar entirely — location box, navigation buttons and overview
`hideHeaderOverview`	keep the header, drop the whole-chromosome overview strip below it
`hideNoTracksActive`	suppress the "No tracks active" placeholder, for an embed that opens with no tracks on purpose
`labelsVisible`	controls whether highlight/bookmark chip labels are shown inline
`legacyBpPerPx`	MIGRATION ONLY, and safe to delete once pre-window sessions are no longer in circulation. A snapshot written before the window was stored carries `offsetPx` and `bpPerPx` but not the width they were measured at, so the window they framed cannot be recovered. `windowStartBp` can (it is `offsetPx * bpPerPx`, no width needed); the width in bp cannot. This carries the old `bpPerPx` to the first measure, which adopts it at whatever width arrives — exactly what the old code did — and clears this. So an old link keeps its old behavior rather than being reinterpreted, and everything authored since restores its window.
`minimized`	collapse the view to its header bar, keeping it in the session rather than closing it
`scalebarOnly`	when true, only the header and coordinate scalebar are rendered
`showAminoAcids`	draw translated codons on coding features once zoomed in far enough: an alternating per-codon shading, and the amino acid letters on top of it at base-level zoom. Independent of `colorByCDS`, which only recolors the segments by frame.
`showCenterLine`	show the "center line"
`showCytobands`	whether to show the "cytobands" in the overview scale bar (the resolved, capability-gated value is the `effectiveShowCytobands` getter)
`showGridlines`	show the "gridlines" in the track area
`showHighlightChips`	pins the interactive highlight chip (link icon + context menu) to every highlight band; off by default, where a band instead reveals its chip while the pointer is in it. This is what a screenshot needs, since nothing hovers in one
`showTrackOutlines`	show the track outlines
`trackLabels`	how to display the track labels, can be "overlapping", "offset", or "hidden", or empty string "" (which results in the LinearGenomeViewPlugin config default being used). the resolved value is the `effectiveTrackLabels` getter. see LinearGenomeViewPlugin https://jbrowse.org/jb2/docs/config/lineargenomeviewplugin/ docs for how conf is used
`trackSelectorType`	vestigial: the hierarchical selector is the only one that exists, so this value is ignored. Retained because saved sessions and configs persist it.
`windowStartBp`	Left edge of the viewport, in linearized bp — the concatenated `displayedRegions` space that `offsetPx` indexes, which carries no inter-region padding, so the two differ only by `bpPerPx`. May be negative, which is the view scrolled past the left end. The viewport is stored as the genomic WINDOW it frames rather than as the pixels that framed it, because pixels mean nothing without the width they were measured at and a snapshot does not carry one. Storing them anyway is why a session authored in a 1000px window used to open at 500px showing half the region its author was looking at, while the same location as a `&loc=` opened correctly — the two ways to share a view disagreed, and only the one that stores intent was right.
`windowWidthBp`	Width of the viewport in bp. Zero means "not established yet": no width has been measured, so there is nothing to divide by. The first measure fills it in, and `bpPerPx` is `windowWidthBp / width` from then on.

Launch key	What it does
`autoDiagonalize`	After tracks load, automatically run the chromosome diagonalization pass so the bottom/vertical axis follows the top/horizontal axis. The canvas is hidden behind a "Reordering chromosomes…" spinner during the wait, so the user doesn't see an undiagonalized flash.
`colorBy`	Initial colorBy. Use 'query' (chromosome painting) for whole-genome views where the default red is hard to distinguish across many ribbons. One of `default`, `strand`, `query`, `target`, `reference`, `identity`, `meanQueryIdentity`, `mappingQuality`, `dnds`, `track`.
`highlight`	loc-strings ("chr1:100-200") or JSON objects matching HighlightType, mirroring LinearGenomeView's init.highlight
`minAlignmentLength`	Per-feature alignment-length filter applied at the renderer. Hides chains shorter than this many bp; cuts the genome-scale hairball.
`showColorLegend`	Show the floating color-by legend on load. Set false to hide it (e.g. a curated demo/screenshot where the legend would clutter the figure).

Property	What it does
`alpha`	Plot-wide alpha applied to every point. View-level for the same reason lineWidth is: the only control is view-level, so storing it per display meant a track shown after the slider moved rendered at the default while the slider said otherwise.
`assemblyNames`	the two assemblies being compared, horizontal axis first. A spec normally names these per axis instead, as `views[0].assembly` and `views[1].assembly`.
`displayName`	displayName is displayed in the header of the view, or assembly names being used if none is specified
`drawCigar`	resolve each alignment's CIGAR into the drawn shape rather than plotting it as a single straight segment
`height`	the height of the plot in pixels
`hview`	the horizontal axis, as a full 1D view state. A spec writes `views[0]` instead, which the launcher resolves into this.
`lineWidth`	Screen-space line width (CSS pixels) applied to every dotplot display in this view. View-level because the GPU pass renders all displays with one uniform.
`lockAspectRatio`	When true, hview and vview are kept at the same bpPerPx so the dotplot stays square. Wheel zoom already preserves the ratio; box-zoom and other independent ops trigger an autorun resync.
`lodMode`	Level-of-detail tier override for PIF adapters. 'auto' uses the adapter's bpPerPx threshold; 'fine'/'coarse' force a tier. Stored view-level so all displays render at the same tier and the menu doesn't need to fan out per display.
`minIdentity`	Hide alignments whose sequence identity is below this fraction (0-1), enforced per feature in buildLineSegments beside minAlignmentLength. A feature carrying no identity at all is kept at every threshold — the alternative blanks a plot whose adapter simply never reported one. View-level, see alpha.
`minimized`	collapse the view to its header bar, keeping it in the session rather than closing it
`showGridlines`	carry each axis' ruler ticks across the plot as faint lines, the way LinearGenomeView's gridlines carry its own down over the tracks
`showHighlightChips`	pins the interactive highlight chip (link icon + context menu) to every highlight band; off by default, where a band instead reveals its chip while the pointer is in it. This is what a screenshot needs, since nothing hovers in one
`trackColorBy`	trackId -> color-by mode for that track alone. Absent means the track follows the view-wide `colorBy`.
`trackColors`	trackId -> explicit color under `colorBy: 'track'`. Absent means the track takes an automatic slot from the palette.
`trackSelectorType`	vestigial: the hierarchical selector is the only one that exists, so this value is ignored. Retained because saved sessions and configs persist it.
`vview`	the vertical axis, the counterpart to `hview`. A spec writes `views[1]`.

Launch key	What it does
`autoDiagonalize`	After tracks load, automatically run the chromosome diagonalization pass so the bottom/vertical axis follows the top/horizontal axis. The canvas is hidden behind a "Reordering chromosomes…" spinner during the wait, so the user doesn't see an undiagonalized flash.
`collapseEmptyRows`	Open any genome row this init gives no tracks collapsed to its ruler. The "No tracks active / Open track selector" block costs ~90px per row, which on a five-row launch is more of the viewport than the ribbons; a row is one click from expanding again (MiniControls, or the view menu's "Rows" → "Expand all views"). Off by default so an authored session keeps its rows as written — the launch dialog turns it on, and offers a checkbox to not.
`colorBy`	Initial colorBy. Use 'query' (chromosome painting) for whole-genome views where the default red is hard to distinguish across many ribbons. One of `default`, `strand`, `query`, `target`, `reference`, `identity`, `meanQueryIdentity`, `mappingQuality`, `dnds`, `track`.
`levelHeights`	Pixel height of each synteny strip, one entry per level. Useful for whole-genome views where the default ~100px is too cramped for the ribbon detail to be readable.
`minAlignmentLength`	Per-feature alignment-length filter applied at the renderer. Hides chains shorter than this many bp; cuts the genome-scale hairball.
`sameScale`	Put every genome row on one bp/px, the coarsest row's, instead of fitting each to the pane width. The largest genome then fills the frame and the rest are drawn shorter in proportion, so a size difference between rows (polyploidy, a genome duplication) is visible as length rather than hidden by the per-row stretch — and orthologs between two rows line up at the same scale on both. Applied last, after any autoDiagonalize pass.
`showColorLegend`	Show the floating color-by legend on load. Set false to hide it (e.g. a curated demo/screenshot where the legend would clutter the figure).

URL query parameter API

Query string or hash fragment#

Linear genome view (simple)#

?config=#

&assembly=#

&loc=#

&regions=#

&highlight=#

&tracklist=#

&nav=#

&tracks=#

&sessionTracks=#

&sessionName=#

&hubURL=#

&renderer=#

&safeMode#

Navigating within the default session#

Which parameter decides the launch#

Session spec#

Session-wide fields#

Fields every view takes#

Glob region names#

Advanced track configuration#

Linear genome view#

Linear genome view properties#

Live example: alignments display settings#

Live example: feature track color#

Live example: highlight a feature, and sort it to the top#

Circular view#

Circular view properties#

Dotplot view#

Dotplot view properties#

Dotplot highlights#

Linear synteny view#

Linear synteny view properties#

Linear synteny view (multi-way)#

Breakpoint split view#

Spreadsheet view#

SV inspector#

Plugin-provided view types#

Tiled views / Workspaces#

Horizontal split example#

Custom panel sizes#

Tabbed panels#

Complex nested layout example#

Other session formats#

&session=json-#

&session=encoded-#

&session=local-#

&session=share-#

Are share links reproducible#

Loading a plugin from a URL#

See also#

Query string or hash fragment

Linear genome view (simple)

?config=

&assembly=

&loc=

&regions=

&highlight=

&tracklist=

&nav=

&tracks=

&sessionTracks=

&sessionName=

&hubURL=

&renderer=

&safeMode

Navigating within the default session

Which parameter decides the launch

Session spec

Session-wide fields

Fields every view takes

Glob region names

Advanced track configuration

Linear genome view

Linear genome view properties

Live example: alignments display settings

Live example: feature track color

Live example: highlight a feature, and sort it to the top

Circular view

Circular view properties

Dotplot view

Dotplot view properties

Dotplot highlights

Linear synteny view

Linear synteny view properties

Linear synteny view (multi-way)

Breakpoint split view

Spreadsheet view

SV inspector

Plugin-provided view types

Tiled views / Workspaces

Horizontal split example

Custom panel sizes

Tabbed panels

Complex nested layout example

Other session formats

&session=json-

&session=encoded-

&session=local-

&session=share-

Are share links reproducible

Loading a plugin from a URL

See also