Basic usage
TL;DR: navigate with the location search box (a gene name or
chr:start-end) plus drag-to-pan and scroll-to-zoom. Add your own data through
the open-track form, or preconfigure it in config.json. The controls below are
shared by JBrowse Web and Desktop.
Linear genome view
To open a linear genome view (LGV), use the menu bar: Add →
Linear genome view
Scrolling
You can scroll using the mouse wheel or by clicking and dragging. The pan buttons in the LGV header also scroll left and right.
Zooming
Use the zoom buttons and slider in the LGV header to zoom in and out. You can also:
- hold
Ctrland use the mousewheel to zoom (on Mac, trackpad pinch-to-zoom also works) - hold
Shiftand click-and-drag to create a rubberband selection - hold
Shiftwithout dragging to reveal a red vertical guide bar
Keyboard shortcuts (when the view is focused):
Ctrl/Cmd+↑: zoom inCtrl/Cmd+↓: zoom outCtrl/Cmd+←/→: pan left/right
The scroll-to-zoom toggle button in the LGV header lets the mouse wheel zoom the
view directly, without holding Ctrl/Cmd. It zooms wherever the pointer is
over the tracks; to scroll the page while it is on, put the pointer on the view
header above the tracks, or use the scrollbar. Shift+wheel stays horizontal
scrolling, which is what every browser does with it.
Reordering tracks
Click and drag up or down on the drag handle on the track labels (indicated by six vertical dots) to reorder tracks.
Reordering views
Views have no drag handle: reorder them from the view menu (hamburger icon) with "Move up"/"Move down".
Using the location search box
The location search box at the top of the LGV accepts several search formats:
- Region and location, e.g.
chr1:1..100orchr1:1-100orchr1 1 100 - Coordinates abbreviated with a unit suffix, e.g.
chr1:34M-35Morchr1:1.5Mb-2Mborchr1 500kb 600kb. These are expanded to whole base pairs on navigation, so the search box reads backchr1:34,000,000..35,000,000 - Assembly, region, and location, e.g.
{hg19}chr1:1-100 - Discontinuous regions (space-delimited, opened side-by-side), e.g.
chr1:1..100 chr2:1..100 - Any of the above with
[rev]appended to horizontally flip the region, e.g.chr1:1-100[rev] - Gene name or feature keyword (if a text index is configured), e.g.
BRCA1
Name searching requires a text index. See the text searching configuration guide for setup.
When you pick a gene or feature from the search results (rather than a plain region), JBrowse navigates to it and highlights the matched feature, pinning it toward the top of its track. The highlight follows the feature as you pan and zoom. Search again to move it, or click the "Clear search highlight" button in the header bar to remove it.
An instance with several annotation tracks indexed will match the same gene in each of them. Those hits describe one place, so JBrowse navigates straight there, through a track you already have open where there is one. The picker appears when the hits point at different places.
Opening tracks
To open a new track or connection, use the menu bar: File → Open track...
To load an entire track hub (UCSC track hub or JBrowse 1 data directory) at
once, use File → Open connection.... See the
Connections guide for details.
A circular plus (+) icon button in the "Available tracks" widget also opens the "Add a track" form.
In the "Add a track" form, you can provide a URL or open a file from your local machine. Which formats need an index:
- BAM - BAI or CSI
- CRAM - CRAI
- Tabix-indexed VCF/GFF/BED - TBI or CSI
- BigWig/BigBed - no index
For remote files, the index is inferred automatically when the filename follows
standard conventions (e.g. file.bam → file.bam.bai), but must be supplied
manually for local files or non-standard names.
Adding many tracks at once
Add multiple tracks at once in the "Add a track" form takes a list of file
URLs, one per line, or a set of local files dropped on it. It types each row
from its extension and pairs an index (.bai, .csi, .tbi, .crai) with its
own data file, so the order they are pasted in does not matter. The preview
table under the box is where a row is renamed or removed; one assembly serves
the whole batch.
File format support
Core JBrowse 2 reads BAM/CRAM, tabix-indexed VCF/GFF3/GTF/BED, BigWig/BigBed,
BedGraph, BEDPE, .hic, MAF/BigMaf/TAF, PLINK LD, and the whole-genome
alignment formats (PAF, MUMmer .delta, UCSC .chain, MCScan .anchors,
MashMap, BLAST tabular), on assemblies stored as indexed FASTA, bgzip-indexed
FASTA, or 2bit. The supported file types table
is the full list, with the adapter and track type each format maps to, and it is
generated from the adapters themselves.
Additional data formats can be supported via plugins; check out the plugin store.
If you are an administrator, you can add tracks with the command line (CLI) or with the admin server (GUI).
Undo and redo
You can undo any action via Tools → Undo/Redo, or with the keyboard shortcuts
ctrl+z/cmd+z (undo) and ctrl+shift+z/ctrl+y/cmd+shift+z (redo).
Undo is app-wide rather than per-view, so it reaches things like reopening a view you just closed, and it works anywhere in JBrowse Web and JBrowse Desktop. The embedded components do not include it.
Sharing sessions
On JBrowse Web, the "Share" button in the main menu bar generates a URL you can send to other users.
The address-bar URL does not capture full session state, so always use the Share button to get a shareable link.
JBrowse Desktop has no Share button, since its sessions are files you can send
directly. It can open a link someone shares with you, though, via File →
Session → Open JBrowse Web link....
The session URL contains:
- the open views and their settings (e.g. track label positioning)
- the tracks in each view, including any you added yourself
- per-track display state, such as an alignments track's soft-clipping and sort settings
This means you can share links with custom tracks without being a JBrowse admin.
Track menu
The track menu (vertical "..." on the track selector or track label) provides access to track-specific functions. Some options are only available when the track is open (from the track label); basic options like "About track" are always available from the track selector.
Favorite and recently used tracks
You can mark favorite tracks from the Track menu and view them using the star icon in the top right corner of the Available tracks widget.
Recently opened tracks are automatically added to the recently used list, viewable via the clock icon in the Available tracks widget.
Feature details
Clicking a feature opens its details panel in the drawer. The Attributes section lists the fields as they came out of the file, so a GFF3 attribute, a BED extra column, or a VCF INFO key appears under its own name.
Two things happen to the values on the way in, with no configuration:
- A value that is just a URL becomes a link, opening in a new tab. So a GFF3
attribute like
url=https://www.uniprot.org/uniprotkb/P12345is clickable as it stands. - HTML is rendered rather than escaped, after being run through a sanitizer.
Text that only looks like a tag is left alone, which is why a VCF
<TRA>allele still reads as<TRA>.
To add fields, rename them, or hide the ones a file carries that your users don't need, see customizing feature details. Gene and transcript features also have a sequence panel, covered in Feature sequence panel.
About track dialog
The track menu provides access to the "About track" dialog.
Opened on a reference sequence track — from the track selector, or from its label when it is open — the dialog also has an "Assembly" section: the assembly's own config (its name, its aliases, and the alias, cytoband and genetic-code files it loads), a "Copy assembly config" button, and "Show ref name aliases", which lists every reference name in the assembly next to the other names it answers to. That listing has a filter box, so it is also how you look up what one contig is called elsewhere.
Editing track configs
Edit any track's settings directly from the track menu's Track actions → Settings item. For non-admin users, edits are saved as a "session track" override that shadows the original, so they persist with (and are shareable via) your session without modifying the underlying admin-owned track. Admin users editing in admin mode change the track config in place.
The configuration editor has a filter box to search options by name, and tucks rarely-needed settings (performance thresholds, adapter internals, and the like) behind a Show advanced settings toggle. If a track has more than one display type, only the currently-active display's settings are expanded; the others collapse out of the way. Use Reset track settings in the track menu to clear your edits and revert to the underlying config.
Pinning a setting as your default
Many track-menu settings (color-by scheme, read and feature height, soft-clipping, and more) carry a small pin next to them. Clicking the pin makes that value the default for every track of the same type, and clicking it again clears the default. Every open track a default affects is badged in the track selector. See defaults for all tracks for the whole system: what follows a default, what keeps its own value, and where the defaults are kept.
The display settings tutorial covers the
same settings from the other direction: as persistent defaults in config.json,
and as overrides carried in a URL or an embedded session.
Rubberband selection
Click and drag on either the main (lower) or overview (upper) scale bar to rubberband-select a region.
The main scale bar's menu holds Zoom to region, Get sequence, Copy range, Highlight region and Bookmark region, plus a Launch submenu of what the loaded plugins can start from the selection:
- Linear synteny view, when a synteny dataset in the session covers this assembly. It opens one panel per assembly aligning to the selection, whether or not the synteny track is turned on. Pick the dataset in its dialog.
- Consensus sequence, when an alignments track is open. Pick the track from the submenu.
Both name the track they run on, because that choice decides the result.
Every entry here has a track-menu twin that takes the visible window instead of a selection, so none of them needs a drag to be found: Get sequence (visible region) on the reference sequence track, Consensus sequence (visible region) on an alignments track, and the synteny launch's own visible-region entry.
Scalebar chromosome name menu
The chromosome (reference sequence) names drawn along the scale bar are clickable. Clicking a name opens a menu with:
- Focus on
<name>- navigate to that entire region - Actions submenu:
- Reverse region - reverse-complement just that region, in place
- Horizontally flip view - reverse-complement the whole view (the same as the header-bar flip described below)
- Move left / Move right and Move to far left / Move to far right - reorder the region relative to the others when multiple regions are displayed (the "far" options appear only when they would land somewhere different from a single-step move)
- Remove this region from view
View and layout controls
Four layout controls, reached from the view's hamburger menu or the header bar.
Show ideogram
When the assembly is configured with cytobands, the overview bar draws the chromosome as a banded ideogram with the centromere marked. Show ideogram toggles it; it is on by default, and the choice is remembered for later sessions.
The entry is absent unless the view is showing a whole chromosome, since a sub-region gives an arbitrary slice of bands and draws the centromere as a lone half triangle.
Track label positioning
Track labels can be positioned on their own row, overlapping the data to save vertical space, or hidden entirely, from the three choices under the Track labels heading in Show... in the view's hamburger menu.
Horizontally flip
The view can be horizontally flipped (reverse complemented), reversing the coordinate direction, from Horizontally flip in the view's hamburger menu. Triangles in the overview bar indicate the current orientation.
Drawer widget position
The drawer widget can be toggled to the left or right side of the screen using the header bar dropdown. It appears on the right by default.
Faceted track selector
The faceted track selector shows all tracks as a filterable table. Open it via the filter icon in the top right of the "Available tracks" widget.
Tracks with metadata fields in their config get extra filterable columns:
{
"trackId": "my_track",
"name": "My Track",
"metadata": { "origin": "public", "date_added": "2024-02-20" }
}See the configuration guide for more.