Skip to content

Embed Options

The embed function accepts an optional options object.

Theme config

The theme embed option provides global defaults without modifying the specification itself:

embed(container, spec, {
  theme: {
    mark: { color: "#1f77b4" },
    point: { size: 80 },
    scale: { nominalColorScheme: "set2" },
  },
});

Theme config is merged before spec.config, so spec-local config and explicit properties still take precedence.

See also Config, Themes, and Styles.

Custom tooltip handlers

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 for readability.

When positional channels use a "locus" scale, the default handler also shows derived genomic rows before raw rows:

  • Coordinate for single positions
  • Interval for genomic ranges
  • Endpoint 1 / Endpoint 2 for two independent endpoints
  • X ... / Y ... prefixes when both axes contribute genomic rows

Raw source fields are hidden only when the mapping from source fields to linearized coordinates can be verified for the hovered datum.

The refseqgene handler fetches a summary description for a gene symbol using the Entrez API. For an example, see 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 to 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?: TooltipHandlerParams,
  /** Optional precomputed context */
  context?: TooltipContext
) => Promise<string | TemplateResult | HTMLElement>;

TooltipContext may include:

  • genomicRows: derived genomic rows
  • hiddenRowKeys: raw row keys hidden by the default handler
  • flattenDatumRows(): utility for flattening datum fields
  • formatting utilities such as formatGenomicLocus() and formatGenomicInterval()

The default handler accepts optional genomic display mode configuration in params:

{
  "genomicCoordinates": {
    "x": { "mode": "auto" },
    "y": { "mode": "disabled" }
  }
}

Supported mode values:

  • "auto" (default)
  • "locus"
  • "interval"
  • "endpoints"
  • "disabled"

The tooltipHandlers option registers custom handlers or overrides the default. See the example below.

Examples

Overriding the default handler:

import { html } from "lit-html";

const options = {
  tooltipHandlers: {
    default: async (datum, mark, params) => 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"
      }
    }
  },
  ...
}