Embedded components

The embedded components are React components published on npm: render one JSX element and you have a genome browser inside your own page. They are the same views the full JBrowse app is built from, so a track config that works there works here.

React 18 or newer is the only peer dependency. If your page isn't a React app, the components also ship as a browser bundle you can load with a single <script> tag, which pulls in the React it needs itself; see non-React hosts below.

Choosing a package#

Each package's storybook is the reference for how to use it: copy-pasteable React code, one page per task — setting up the view, navigating from your own code, running a worker, theming, plugins, and more. Start there for anything beyond the basic props below.

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 single-view components' one assembly, or from an app config declaring just one (see the shortest track).

@jbrowse/react-app2 also needs its stylesheet: import '@jbrowse/react-app2/styles.css'. It is the only one of these packages that ships a stylesheet; without it the panels, tabs and dividers render unstyled while everything else looks correct.

The props are initial values, like an input's defaultValue. The engine is built once, on first render, and later prop changes are ignored — so pointing an already-mounted component at a different assembly, or a different plugin list, does nothing. Give the element a React key that changes with the assembly and React remounts it on a fresh engine.

Embedded views versus the full app#

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

Embedded components are designed for web developers to build custom systems around, so features like sessions and track manipulation can be implemented by the embedding application. If your app is Python or R rather than JavaScript, 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 one from your own code — reading state back out, local in-process data, the controller's callbacks — is covered in Automating JBrowse.

Bundler examples#

See also#

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