Embedding JBrowse

A genome browser can sit inside a page of your own, such as a lab site, a data portal or a report, showing your genome and your tracks beside the rest of the page. JBrowse's linear genome view ships as a component for this, and one <script> tag loads it with no build step. The <LinearGenomeView> component takes three objects, assembly, tracks and view, and draws the browser from them. We:

• embed the view in an HTML page with one script tag
• point its assembly and tracks at your own data files
• use the same component in a React app, with useCreateViewState for control from code

Prerequisites#

• a text editor
• a local HTTP server, because the page fetches its data over HTTP. npx serve -S in the folder works (-S resolves symlinks, so a data file you symlink in still loads)

Embed a linear genome view with one script tag#

Save this page as index.html:

<!doctype html>
<html>
  <head>
    <meta charset="UTF-8" />
    <title>JBrowse Linear Genome View</title>
    <script
      src="https://unpkg.com/@jbrowse/react-linear-genome-view2@next/dist/react-linear-genome-view.umd.production.min.js"
      crossorigin
    ></script>
  </head>
  <body>
    <div id="jbrowse_linear_genome_view"></div>
    <script>
      const { React, createRoot, LinearGenomeView } =
        JBrowseReactLinearGenomeView

      const assembly = {
        name: 'hg38',
        uri: 'https://jbrowse.org/genomes/GRCh38/fasta/hg38.prefix.fa.gz',
        refNameAliases: {
          uri: 'https://jbrowse.org/genomes/GRCh38/hg38_aliases.txt',
        },
        geneticCodes: { chrM: 2 },
      }

      const tracks = [
        {
          trackId: 'ncbi_genes',
          name: 'NCBI RefSeq Genes',
          uri: 'https://jbrowse.org/genomes/GRCh38/ncbi_refseq/GCA_000001405.15_GRCh38_full_analysis_set.refseq_annotation.sorted.gff.gz',
        },
      ]

      const view = {
        loc: '10:29,838,565..29,838,850',
        tracks: ['ncbi_genes'],
      }

      const root = createRoot(
        document.getElementById('jbrowse_linear_genome_view'),
      )
      root.render(
        React.createElement(LinearGenomeView, { assembly, tracks, view }),
      )
    </script>
  </body>
</html>

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

npx serve -S .

Open the URL serve prints.

The @next tag fetches the newest v5 prerelease, which the assembly and tracks shorthand above needs. For production, pin the version you tested against in place of @next (@jbrowse/react-linear-genome-view2@<version>). For other view types, a different bundler, or working demo repos, see Embedded components.

Using your own data files in the embedded view#

The browser fetches each file itself, so each must be reachable and indexed:

• A relative uri such as uri: 'sample.bam' resolves against the page, so with npx serve -S . a file beside index.html loads. Use a full URL for a file hosted elsewhere.
• A BAM, CRAM, VCF or GFF is indexed (.bai, .crai, .tbi, .csi) with the index beside the file under the same name plus its suffix. A VCF or GFF is bgzipped; a FASTA has its .fai, and a bgzipped one its .gzi.
• A file on another origin needs CORS headers allowing the page's origin and Range requests, because the browser reads slices.
• Sequence names in tracks match the assembly's, or the assembly's refNameAliases map them.

Prep your own data files with the web quickstart recipes.

Using the component in a React app#

In a React app, pass the same assembly, tracks, and view as props:

import { LinearGenomeView } from '@jbrowse/react-linear-genome-view2'

function GenomeBrowser() {
  return <LinearGenomeView assembly={assembly} tracks={tracks} view={view} />
}

The component reads its props once, on mount. To navigate or show a track from code afterwards, take a ref or use useCreateViewState, which builds the same view state as a hook.

useCreateViewState also destroys the view when the component unmounts, which <LinearGenomeView> leaves running, so use it in a component that mounts and unmounts repeatedly, such as an app route. It returns undefined until it has built the view, so render nothing until then:

import {
  useCreateViewState,
  JBrowseLinearGenomeView,
} from '@jbrowse/react-linear-genome-view2'

function GenomeBrowser() {
  const state = useCreateViewState({ assembly, tracks, location: '...' })
  return state ? <JBrowseLinearGenomeView viewState={state} /> : null
}

A more complete example#

Swap in the example below to draw genes, reads, conservation and variants in one view.

const assembly = {
  name: 'hg38',
  uri: 'https://jbrowse.org/genomes/GRCh38/fasta/hg38.prefix.fa.gz',
  refNameAliases: {
    uri: 'https://jbrowse.org/genomes/GRCh38/hg38_aliases.txt',
  },
  cytobands: {
    uri: 'https://jbrowse.org/genomes/GRCh38/cytoBand.txt',
  },
  geneticCodes: { chrM: 2 },
}

const tracks = [
  {
    trackId: 'ncbi_genes',
    name: 'NCBI RefSeq Genes',
    category: ['Genes'],
    uri: 'https://jbrowse.org/genomes/GRCh38/ncbi_refseq/GCA_000001405.15_GRCh38_full_analysis_set.refseq_annotation.sorted.gff.gz',
    textSearching: {
      textSearchAdapter: {
        uri: 'https://jbrowse.org/genomes/GRCh38/ncbi_refseq/trix/GCA_000001405.15_GRCh38_full_analysis_set.refseq_annotation.sorted.gff.gz.ix',
      },
    },
  },
  {
    trackId: 'repeats_hg38',
    name: 'Repeats',
    category: ['Annotation'],
    uri: 'https://jbrowse.org/genomes/GRCh38/repeats.bb',
  },
  {
    trackId: 'NA12878_exome',
    name: 'NA12878 Exome',
    category: ['1000 Genomes', 'Alignments'],
    uri: 'https://jbrowse.org/genomes/GRCh38/alignments/NA12878/NA12878.alt_bwamem_GRCh38DH.20150826.CEU.exome.cram',
  },
  {
    trackId: '1000g_vcf',
    name: '1000 Genomes Variant Calls',
    category: ['1000 Genomes', 'Variants'],
    uri: 'https://jbrowse.org/genomes/GRCh38/variants/ALL.wgs.shapeit2_integrated_snvindels_v2a.GRCh38.27022019.sites.vcf.gz',
  },
  {
    trackId: 'phyloP100way',
    name: 'hg38.100way.phyloP100way',
    category: ['Conservation'],
    uri: 'https://hgdownload.soe.ucsc.edu/goldenpath/hg38/phyloP100way/hg38.phyloP100way.bw',
  },
]

const view = {
  loc: '10:29,838,565..29,838,850',
  tracks: ['ncbi_genes', 'NA12878_exome', 'phyloP100way', '1000g_vcf'],
}

Serve the folder again and open the URL it prints:

npx serve -S .

See also#

• Tutorial: JBrowse CLI with Desktop
• Tutorial: Display settings
• Config guide: Assemblies
• Config guide: Tracks
• Docs: Embedded components
• Docs: jbrowse-anywidget
• Docs: JBrowseR
• LGV storybook

Feedback on this tutorial is welcome: contact us.