Vega-Embed

Vega-Embed makes it easy to embed interactive Vega and Vega-Lite visualizations into web pages. It provides a simple API for loading visualization specifications from various sources, includes built-in action menus for exporting charts and viewing source code, supports custom theming, and includes tooltip functionality for interactive data exploration.

Package Information

• Package Name: vega-embed
• Package Type: npm
• Language: TypeScript
• Installation: npm install vega-embed

Core Imports

import embed from "vega-embed";

For CommonJS:

const embed = require("vega-embed");

Named imports (access properties on default export):

import vegaEmbed from "vega-embed";

// Access functions and properties
vegaEmbed.embed(el, spec, opts);
vegaEmbed.container(spec, opts);
vegaEmbed.vega;
vegaEmbed.vegaLite;
vegaEmbed.vl; // backwards compatibility alias for vegaLite
vegaEmbed.version;

Basic Usage

import embed from "vega-embed";

// Embed a Vega-Lite specification
const spec = {
  mark: "bar",
  data: { values: [{ a: "A", b: 28 }, { a: "B", b: 55 }] },
  encoding: {
    x: { field: "a", type: "ordinal" },
    y: { field: "b", type: "quantitative" }
  }
};

const result = await embed("#vis", spec);
console.log(result.view); // Access the Vega view instance

Architecture

Vega-Embed is built around several key components:

• Embed Function: Main entry point for embedding Vega/Vega-Lite visualizations in DOM elements
• Container Function: Creates standalone div containers with embedded visualizations, designed for Observable
• Options System: Comprehensive configuration for rendering, theming, actions, and interactions
• Mode Detection: Automatic detection of Vega vs Vega-Lite specifications
• Action System: Built-in menu system for export, source viewing, and editor integration
• Patch System: Support for spec modification and dynamic configuration

Capabilities

Core Embedding

Main embedding functionality for integrating Vega and Vega-Lite visualizations into web applications. Handles spec loading from URLs or objects, with comprehensive configuration options.

function embed(
  el: HTMLElement | string,
  spec: VisualizationSpec | string,
  opts?: EmbedOptions
): Promise<Result>;

type VisualizationSpec = VlSpec | VgSpec;

interface Result {
  view: View;
  spec: VisualizationSpec;
  vgSpec: VgSpec;
  embedOptions: EmbedOptions;
  finalize: () => void;
}

Core Embedding

Container Creation

Specialized function for creating standalone visualization containers with embedded views, optimized for Observable and interactive environments.

function container(
  spec: VisualizationSpec | string,
  opt?: EmbedOptions
): Promise<HTMLDivElement & { value: View }>;

Container Creation

Configuration Options

Comprehensive configuration system for customizing visualization rendering, appearance, interactions, and behavior.

interface EmbedOptions<S = string, R = Renderers> {
  bind?: HTMLElement | string;
  actions?: boolean | Actions;
  mode?: Mode;
  theme?: keyof Omit<typeof themes, 'version'>;
  defaultStyle?: boolean | string;
  renderer?: R;
  tooltip?: TooltipHandler | TooltipOptions | boolean;
  patch?: S | PatchFunc | Operation[];
  width?: number;
  height?: number;
  config?: S | Config;
  // ... additional options
}

Configuration Options

Actions and Interactions

Built-in action menu system providing export functionality, source viewing, and editor integration for enhanced user interaction with visualizations.

interface Actions {
  export?: boolean | { svg?: boolean; png?: boolean };
  source?: boolean;
  compiled?: boolean;
  editor?: boolean;
}

const DEFAULT_ACTIONS: Actions;

Actions and Interactions

Utilities and Helpers

Utility functions for mode detection, URL validation, and configuration merging to support the core embedding functionality.

function guessMode(spec: VisualizationSpec, providedMode?: Mode): Mode;
function isURL(s: string): boolean;
function mergeDeep<T>(dest: T, ...src: readonly DeepPartial<T>[]): T;

type Mode = 'vega' | 'vega-lite';

Utilities and Helpers

Re-exported Libraries

Vega-Embed re-exports the core Vega and Vega-Lite libraries for convenience:

const vega: typeof vegaImport;
let vegaLite: typeof vegaLiteImport;
const version: string;

These exports provide direct access to the underlying visualization libraries and package version information.