JavaScript API¶

The public JavaScript API is currently quite minimal.

Embedding¶

The API¶

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 on using the API, check the embed-examples package.

Embed options¶

The embed function accepts an optional options object.

Named data provider¶

See the API definition.

GenomeSpy provides two built-in tooltip handlers.

The default handler displays the underlying datum's properties in a table. Property names starting with an underscore are omitted. The values are formatted nicely.

The refseqgene handler fetches a summary description for a gene symbol using the Entrez API. For an example, check the RefSeq gene track in this notebook. Custom search terms can be provided through the params property.

Handlers are functions that receive the hovered mark's underlying datum and return a promise that resolves into a string, HTMLElement, or lit-html TemplateResult.

The function signature:

export type TooltipHandler = (
  datum: Record<string, any>,
  mark: Mark,
  /** Optional parameters from the view specification */
  params?: Record<string, any>
) => Promise<string | TemplateResult | HTMLElement>;

Use the tooltipHandlers option to register custom handlers or override the default. See the example below.

Examples¶

Overriding the default handler:

import { html } from "lit-html";

const options = {
  tooltipHandlers: {
    default: async (datum, mark, props) => html`
      The datum has
      <strong>${Object.keys(datum).length}</strong> attributes!
    `,
  },
};

embed(container, spec, options);

To use a specific (custom) handler in a view specification:

{
  "mark": {
    "type": "point",
    "tooltip": {
      "handler": "myhandler",
      "params": {
        "custom": "param"
      }
    }
  },
  ...
}