Embedding GenomeSpy¶

Embedding¶

See the getting started page. For specifications stored as JSON files, turn on editor suggestions and error checking to catch many common mistakes before the specification reaches the browser.

Entry points¶

When embedding GenomeSpy into a web application, you can choose between two entry points for importing the embed function.

Default¶

@genome-spy/core is the default entry point. It includes the standard GenomeSpy runtime and the built-in data source and format registrations.

import { embed } from "@genome-spy/core";

const spec = {
  // view specification
};

const api = await embed(document.body, spec);

Minimal¶

@genome-spy/core/minimal provides the same embed API without built-in renderers or optional data loaders. Import at least one live renderer and any data source or format modules you need explicitly:

import { embed } from "@genome-spy/core/minimal";
import "@genome-spy/core/rendering/webgl.js";
import "@genome-spy/core/rendering/canvas.js";
import "@genome-spy/core/data/formats/parquet.js";
import "@genome-spy/core/data/sources/lazy/bigBedSource.js";

const spec = {
  // view specification that uses the lazy bigBed source
};

const api = await embed(document.body, spec);

See the full runtime entry point for the complete list of optional modules.

The webgl.js import enables WebGL2. The canvas.js import enables Canvas2D. Import svg.js when using SVG export. You can omit any renderer capability the host application does not use; Core reports the required import if an unavailable capability is requested.

API object¶

The embed function returns a promise that resolves into an object that provides the current public API. The API is documented in the interface definition.

For practical examples of using the API, explore the live embed examples or browse their source in the embed-examples package.

The embed API includes api.events, api.params, and api.views. Use api.events for synchronous canvas input, api.params for top-level state, and the params and marks namespaces on view handles for view-scoped state and interaction. These namespaces return unsubscribe functions and are disconnected by finalize().

Optional controls¶

attachControls mounts an explicit, ordered list of controls. It provides styles and hover/focus visibility but does not register renderers.

import { embed } from "@genome-spy/core/minimal";
import "@genome-spy/core/rendering/webgl.js";
import "@genome-spy/core/rendering/svg.js";
import {
  attachControls,
  pngButton,
  svgButton,
  fullWindowButton,
} from "@genome-spy/core/controls";

const container = document.getElementById("plot");
const api = await embed(container, spec);
const controls = attachControls(container, api, {
  controls: [pngButton({ filename: "plot" }), svgButton(), fullWindowButton()],
});

// Before replacing or removing the embed:
controls.dispose();
api.finalize();

pngButton and svgButton accept two options:

• filename: the download name without an extension; defaults to "genomespy".
• exportOptions: settings passed to the image export API.

button({ label, onClick }) adds a custom text button. The label also serves as its accessible name and hover title. Set icon to an SVG or HTML element for an icon button. An optional title overrides the hover tooltip.

See the commented example for custom actions, or the Control contract for controls with their own lifecycle.

genomeSpyButton() adds a favicon link to the GenomeSpy website, opening in a new tab. The Inspector package also provides an inspectorButton().

All placements attach to the same container without changing its size. Top/bottom controls sit outside it: provide space (e.g. margin-block: 48px) and allow overflow. Inside controls overlay the plot.

Debugging embeds¶

Use the Inspector to inspect the live view hierarchy, resolutions, params, and dataflow of embedded visualizations. Core embeds can attach the inspector through the @genome-spy/inspector package.