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 18 or newer is the only peer dependency. For a page that isn't a React app, a <script> bundle carries 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 also needs its stylesheet: import '@jbrowse/react-app2/styles.css'. Without it the panels, tabs and dividers render unstyled.

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. It's what the Python anywidget, R htmlwidgets, and plain <script> pages are built on. See the vanillajs rows in bundler examples below for a working reference implementation of each.

Driving it from your code#

createViewState takes the same view fields a config or a link does (Config and session JSON), and routes location and highlight through the same launch path, so an embedded view shows the loading spinner while the assembly loads:

const state = createViewState({
  assembly,
  tracks,
  location: 'chr1:1,000-2,000',
  highlight: ['chr1:1,500-1,600'],
})

• Full track control at launch is a defaultSession whose view names its tracks (Embedding JBrowse).
• 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