@weng-lab/genomebrowser

A React runtime for displaying interactive genomic tracks.

Create browser and track stores, add track modules, and pass the stores to GenomeBrowser. Use first-party modules for common file formats or define custom track types.

Install

pnpm add @weng-lab/[email protected] @weng-lab/[email protected] react@^19.2.0 react-dom@^19.2.0 @emotion/react@11 @emotion/styled@11 @mui/material@7

Quick start

Create the browser and track stores once, outside component rendering, then pass them to GenomeBrowser.

import { GenomeBrowser, createBrowserStore, createTrackStore, hg38 } from "@weng-lab/genomebrowser";
import { bigWigModule } from "@weng-lab/genomebrowser-tracks/bigwig";

const useBrowserStore = createBrowserStore({
  assembly: hg38,
  region: { chromosome: "chr1", start: 1_000_000, end: 1_100_000 },
});

const useTrackStore = createTrackStore({
  modules: [bigWigModule],
  tracks: [
    bigWigModule.create({
      base: {
        id: "signal",
        title: "Signal",
      },
      config: {
        url: "YOUR_URL_HERE",
      },
    }),
  ],
});

export function BrowserPage() {
  return <GenomeBrowser browserStore={useBrowserStore} trackStore={useTrackStore} />;
}

Replace YOUR_URL_HERE with a BigWig URL accessible from the browser.

Store factory results are Zustand hooks, so their names should begin with use. Keep both stores stable. Recreating them during render resets browser state and request coordination.

For a responsive browser that follows its container width, see Getting started.

Optional packages

Start with this package when you need to render or control a genome browser.

Add @weng-lab/[email protected] for controls such as track selection from collections or cytoband navigation. The optional UI package and GenomeBrowser can share the same track store.

Add @weng-lab/[email protected] for the BigBed, BigWig, BulkBed, CAVE, cCRE BigBed, MethylC, and Gene modules. Core does not export first-party track implementations.

Documentation

Before writing or changing an integration, read node_modules/@weng-lab/genomebrowser/docs/README.md in your application, then follow its links to the relevant guides and API references. These bundled docs describe the installed package version. Give coding agents this path so they use the same version-specific documentation.

• Documentation overview. Learning path and topic navigation.
• Getting started. Install and render a responsive browser.
• API reference. Browser component, viewport store, assemblies, and regions.
• Troubleshooting. Diagnose setup and runtime problems.

Runtime requirements

Genome Browser v2 runs in React 19.2+ client applications. It uses SVG, pointer events, and remote data requests. Responsive sizing also requires ResizeObserver. Render it on the client rather than on the server.

Coordinate rulers are regular tracks supplied by @weng-lab/genomebrowser-tracks/ruler. Add one explicitly if needed. Region selection modes work across the browser independently of the ruler.

Track collections covers the shared JSON format, validation, and genomebrowser schema CLI.