URL query parameter API

JBrowse Web reads its launch state from the URL. Embedded components such as @jbrowse/react-linear-genome-view2 leave URL handling to the host app.

Query string or hash fragment

Every parameter works in either place: ?config=…&loc=… or #config=…&loc=….
A fragment is never sent to the server, so a long value (an encoded- or json- session, a whole session spec, a big &sessionTracks=) cannot trip the request-line limit that answers a long query string with HTTP 414. The Share button writes its inline formats as hash URLs for that reason.
If the fragment contains an =, JBrowse reads its parameters only from there and ignores the query string. 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)

One linear genome view, from a handful of parameters:

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 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.
&password= belongs to &session=share-, and &adminKey= to JBrowse CLI admin server.

?config=

?config=test_data/volvox/config.json

A path to a config file, relative to the current folder, fetched by the client. Omitted, JBrowse loads config.json from the current folder, which is what @jbrowse/cli sets up.
?config=none skips the config entirely, for a &hubURL= that supplies its own assemblies and tracks.
To change the default without putting ?config= in every link, set window.__jbrowseConfigPath in the <head> of index.html (Avoiding stale config). An explicit ?config= still wins.

&assembly=

&assembly=hg19, the name of an entry in the config's assemblies array.

&loc=

&loc=chr1:6000-7000, navigated to on load. Accepted forms:

&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 takes a k, M or G suffix, optionally followed by b or bp, and is expanded to whole base pairs on load.
A gene name needs a text index built with jbrowse text-index.
Several whitespace-separated locstrings (%20 in a URL) open a discontinuous view showing each region in turn: a gene and its fusion partner, an allele beside the sequences it derives from. The location box displays the same form once a view holds more than one region, so what you copy out of it pastes back into a URL.
&loc= and &assembly= start a fresh session, ignoring the config's defaultSession; &extendSession=true navigates that session instead.

&regions=

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

Restricts the whole-genome overview to this subset of the assembly's chromosomes, in this order, for dropping unplaced contigs or reordering. Names resolve through the assembly's aliases and take globs. It requires &assembly=, is ignored when &loc= is set, and is the simple-URL form of the spec's displayedRegionNames.

&highlight=

&highlight=chr1:6000-7000, a band over the region on every track, with &assembly= and &loc=.

Several regions are space-separated (%20).
Always pass &assembly=. Highlights are stored by assembly name so the chip menu's actions can resolve them; the same applies to view.highlight in a session JSON, where each entry takes assemblyName.
A URL-encoded JSON object in place of a locstring adds color (used as-is, alpha included) and label (shown beside the chip icon): &highlight={"refName":"11","start":32200274,"end":32203877,"color":"rgba(240,128,128,0.3)","label":"R2_intron"}. Locstrings and JSON objects can be mixed in one value.
To box one feature by name and sort it to the top of its track, see featureHighlights.

&tracklist=

&tracklist=true opens the track selector on load. Default false.

&nav=

&nav=false hides the linear genome view's navigation bar. Default true.

&tracks=

&tracks=gene_track,vcf_track, a comma-separated list of trackIds from the config. A trackId added by &sessionTracks= can be named here too.

&sessionTracks=

Adds track configs to the session from the URL. A track over a data file needs no type or adapter, since the extension gives both, but nothing implies its assembly, so name it (the shortest track):

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

A track with no data file, such as BLAST hits carried inline as a FromConfigAdapter, takes the full form. Live link, whose value pretty-printed 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 names the session in the header bar, for any launch type. Without it the name is generated with a timestamp.

&hubURL=

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

Loads one or more UCSC track hubs (comma-separated) as a session, usually with ?config=none since the hub supplies its own assemblies and tracks.
&assembly= and &loc= open the hub at a place; &assembly= is required, since it names the hub genome &loc= resolves against: ?config=none&hubURL=https://example.com/hub.txt&assembly=GCF_019202715.1&loc=chr1:1-100000.
&sessionTracks= registers into the hub session, so &tracks= can name one of them beside the hub's own.
Each hub opens with a single linear genome view. For several views, a workspace layout or a dotplot, put the hub in a session spec's sessionConnections.
Opening track hubs by URL is the full workflow.

&renderer=

&renderer=webgl pins the drawing backend, overriding detection: webgpu, webgl, or canvas2d (alias canvas). A pin never falls through, so a backend that cannot start shows an error on every track. It is a debugging aid (my tracks are blank), and JBrowse Desktop takes the same choice as --renderer.

&safeMode

&safeMode, bare, loads without the plugins this browser keeps for this configuration, for one load only. Its 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.

Navigating within the default session

&extendSession=true beside &loc= navigates a curated defaultSession instead of replacing it:

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

&loc=, &tracks=, &highlight=, &nav= and &tracklist= then apply to the first linear genome view of that session, whose assembly is used, so &assembly= is not needed. &sessionTracks= is not layered on; a 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 do not combine: one decides what opens and the rest are layered onto it or dropped. Highest first:

&session=, in any form (spec-, share-, encoded-, json-, local-). A value matching none of those prefixes is an error.
&extendSession=true beside &loc=/&assembly=, which navigates the config's defaultSession. It outranks a hub, which would otherwise replace that session.
&hubURL=. A link carrying both a hub and &loc= navigates inside the hub.
&loc=/&assembly= on their own, a fresh single linear genome view.
Nothing of the above 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, and is not layered onto a default session or any &session=, which carry tracks their own way.

Session spec

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

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

{
  "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
`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.

Property	What it does
`autoFit`	whether the view keeps re-fitting to its container on resize. Cleared once the user manually zooms/pans so their view (persisted via bpPerPx/offsetRadians) is preserved across resizes and reloads.
`bpPerPx`	the zoom level, base-pairs per pixel. Capped by `minimumRadiusPx`, and refit over by the first resize unless `autoFit` is false.
`disableImportForm`	suppress the import form even on an error — what the SV inspector's circle wants, since its assembly comes from the sheet beside it and a form there would offer a control that cannot work
`displayName`	displayName is displayed in the header of the view, or assembly names being used if none is specified
`height`	the height of the view in pixels. The circle auto-fits its container, so this is what sizes the drawing.
`hideTrackSelectorButton`	chrome switch, for an embed that drives the view itself
`hideVerticalResizeHandle`	chrome switch, for an embed that drives the view itself
`minimized`	collapse the view to its header bar, keeping it in the session rather than closing it
`minimumRadiusPx`	how far in the circle may be zoomed, as a floor on the radius; it is what caps bpPerPx
`minVisibleWidth`	arcs thinner than this many pixels are elided instead of drawn, which is what stops a few thousand unplaced contigs becoming a ring of hairlines
`offsetRadians`	similar to offsetPx in linear genome view
`paddingPx`	blank margin between the circle and the edge of the figure
`spacingPx`	the gap drawn between adjacent chromosome arcs
`trackSelectorType`	vestigial: the hierarchical selector is the only one that exists, so this value is ignored. Retained because saved sessions and configs persist it.

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.
`highlight`	loc-strings ("chr1:100-200") or JSON objects matching HighlightType, mirroring LinearGenomeView's init.highlight

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`.
`colorBy`	The color-by mode the whole view renders with, unless a track overrides it in `trackColorBy`. One of `default`, `strand`, `query`, `target`, `reference`, `identity`, `meanQueryIdentity`, `mappingQuality`, `dnds`, `track`.
`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.
`minAlignmentLength`	Hide alignments shorter than this many bp. Enforced per feature in buildLineSegments. Cuts whole-genome hairball noise. View-level, see alpha.
`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
`showColorLegend`	Show the floating color-by legend. Dismissible via the legend's close button; re-enable from the color-by (palette) menu.
`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]`.

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#

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

Other session formats

&session=json-

&session=encoded-

&session=local-

&session=share-

Are share links reproducible

Loading a plugin from a URL

See also