Embedded components

The embedded components are React components on npm: one JSX element puts a genome browser in your page. They are the same views the full app is built from, so a track config that works there works here.

React 19 or newer is the only peer dependency. For a page that isn't a React app, a <script> bundle includes its own React; see non-React hosts.

Choosing a package#

Each package's storybook is the reference: copy-pasteable React code, one page per task (setting up the view, navigating from your own code, running a worker, theming, plugins).

A tracks entry is a track config, and the shortest one is { trackId, uri }. The type and adapter come from the file's extension, and assemblyNames from the component's one assembly (see the shortest track).

@jbrowse/react-app2 has a stylesheet to import: import '@jbrowse/react-app2/styles.css'. It holds no rules today, and it is where the package ships any CSS it comes to need.

The props are initial values, like an input's defaultValue. The engine is built once on first render and later prop changes are ignored. To switch assembly or plugins on a mounted component, give it a React key that changes with them so React remounts it.

Embedded views versus the full app#

Embedded views are for genome browsing inside an existing page. For a standalone browser, run JBrowse Web. @jbrowse/react-app2 sits between: the whole app as a React component.

Sessions and track manipulation are left to the embedding application. For Python or R, jbrowse-anywidget and JBrowseR wrap the same views.

Non-React hosts#

Every package also exports an imperative controller — createLinearGenomeView, createCircularGenomeView, createApp — with no JSX and no React root for you to manage. The Python anywidget, R htmlwidgets, and plain <script> pages are built on these controllers. See the vanillajs rows in bundler examples below for a working reference implementation of each.

Driving it from your code#

createViewState takes the view to open as view, written with the same fields a config or a link uses (Config and session JSON): where it opens and which tracks it shows, with any of the view's own settings beside them. An embedded view shows the loading spinner while the assembly loads:

const state = createViewState({
  assembly,
  tracks,
  view: {
    loc: 'chr1:1,000-2,000',
    tracks: ['genes'],
    highlight: ['chr1:1,500-1,600'],
    hideHeader: true,
  },
})

• location and highlight are shorthands for view.loc and view.highlight, and the only two that also apply over a defaultSession or a restored session. view is the default session's view, so it excludes defaultSession (Embedding JBrowse).
• jbrowseHub: 'hg38' in place of assembly fetches that genome from genomes.jbrowse.org: its sequence, refName aliases, track catalog and gene-name search, so view: { loc: 'BRCA1' } works and tracks adds your own files beside the hosted ones. Any UCSC database name or GenArk accession resolves. It is fetched, so it goes to useCreateViewState or createViewStateAsync; the imperative createLinearGenomeView takes the same name as its assembly. The circular view takes a list, jbrowseHub: ['hg38', 'mm39'], for two genomes on one circle.
• localFiles, a name -> bytes map, serves a host whose data lives in a process rather than at a URL: a notebook kernel, an R session, anywhere with no web server and no CORS. tracks then refers to a registered name as if it were a URL. Register an index under its conventional sibling name (peaks.bed.gz + peaks.bed.gz.tbi) and only the bytes the view needs are read.
• menuBar draws the app-shaped File menu bar above the embedded linear view, with the two items an embed can honour (open track, open connection); disableAddTracks empties that menu and removes the track selector's add-track affordances. Both are off by default. height sets the view's height; it supersedes the older drawerViewHeight, which only applied while a drawer was open.
• The imperative controllers take callbacks in place of props: onLocationChange fires with the visible region as the user pans or zooms, onFeatureSelect with the clicked feature, onSessionChange with the view's layout whenever it settles (for a host offering "save this view"), and onError when the build itself fails, since building is asynchronous and that throw cannot reach your own call. createApp's onPluginsUpdated fires when something changes the running plugin set, with what a rebuild needs to remount the app on the new set.

Bundler examples#

See also#

• Embedding JBrowse
• jbrowse-anywidget: Python equivalent
• JBrowseR: R/Shiny equivalent