tessl/npm-vega-embed

Publish Vega visualizations as embedded web components.

—

Pending

Overview

Eval results

Files

Configuration Options

Name: tessl/npm-vega-embed
Author: tessl

Comprehensive configuration system for customizing visualization rendering, appearance, interactions, and behavior. The EmbedOptions interface provides fine-grained control over all aspects of the embedding process.

Capabilities

EmbedOptions Interface

Main configuration interface with extensive customization options.

interface EmbedOptions<S = string, R = Renderers> {
  /** Element to bind interactions to (defaults to the visualization element) */
  bind?: HTMLElement | string;
  
  /** Configure action menu buttons (export, source, compiled, editor) */
  actions?: boolean | Actions;
  
  /** Force interpretation as 'vega' or 'vega-lite' (auto-detected if not provided) */
  mode?: Mode;
  
  /** Apply a Vega theme (e.g., 'dark', 'excel', 'ggplot2', 'quartz') */
  theme?: keyof Omit<typeof themes, 'version'>;
  
  /** Include default CSS styling (true by default) */
  defaultStyle?: boolean | string;
  
  /** Set logging level (0=none, 1=warn, 2=info, 3=debug) */
  logLevel?: number;
  
  /** Configure data loading behavior */
  loader?: Loader | LoaderOptions;
  
  /** Rendering backend ('canvas' or 'svg') */
  renderer?: R;
  
  /** Configure tooltip behavior */
  tooltip?: TooltipHandler | TooltipOptions | boolean;
  
  /** Specification patches to apply */
  patch?: S | PatchFunc | Operation[];
  
  /** Override visualization width */
  width?: number;
  
  /** Override visualization height */
  height?: number;
  
  /** Set padding around the visualization */
  padding?: number | { left?: number; right?: number; top?: number; bottom?: number };
  
  /** Scale factor for exports */
  scaleFactor?: number | { svg?: number; png?: number };
  
  /** Vega/Vega-Lite configuration object */
  config?: S | Config;
  
  /** Header text for source view */
  sourceHeader?: string;
  
  /** Footer text for source view */
  sourceFooter?: string;
  
  /** Custom URL for Vega Editor */
  editorUrl?: string;
  
  /** Configure hover interactions */
  hover?: boolean | Hover;
  
  /** Internationalization strings */
  i18n?: Partial<typeof I18N>;
  
  /** Default filename for downloads */
  downloadFileName?: string;
  
  /** Number formatting locale */
  formatLocale?: Record<string, unknown>;
  
  /** Time formatting locale */
  timeFormatLocale?: Record<string, unknown>;
  
  /** Custom expression functions */
  expressionFunctions?: ExpressionFunction;
  
  /** Enable AST parsing mode */
  ast?: boolean;
  
  /** Custom expression interpreter */
  expr?: typeof expressionInterpreter;
  
  /** Custom View class */
  viewClass?: typeof View;
  
  /** Always show actions menu (even for small charts) */
  forceActionsMenu?: boolean;
}

Actions Configuration

Configure the action menu buttons that appear with visualizations.

interface Actions {
  /** Enable export actions (PNG/SVG download) */
  export?: boolean | { svg?: boolean; png?: boolean };
  
  /** Enable "View Source" action */
  source?: boolean;
  
  /** Enable "View Compiled Vega" action */
  compiled?: boolean;
  
  /** Enable "Open in Vega Editor" action */
  editor?: boolean;
}

/** Default actions configuration */
const DEFAULT_ACTIONS: Actions = {
  export: { svg: true, png: true },
  source: true,
  compiled: true,
  editor: true
};

Usage Examples:

// Disable all actions
await embed("#vis", spec, { actions: false });

// Enable only export
await embed("#vis", spec, { actions: { export: true } });

// Customize export formats
await embed("#vis", spec, {
  actions: {
    export: { svg: true, png: false },
    source: true,
    compiled: false,
    editor: false
  }
});

Hover Configuration

Configure hover interactions and visual feedback.

interface Hover {
  /** Encoding set name for hover highlighting */
  hoverSet?: EncodeEntryName;
  
  /** Encoding set name for updates */
  updateSet?: EncodeEntryName;
}

Usage Examples:

// Enable hover interactions
await embed("#vis", spec, { hover: true });

// Custom hover configuration
await embed("#vis", spec, {
  hover: {
    hoverSet: "hover",
    updateSet: "update"
  }
});

Patching Configuration

Support for dynamically modifying specifications before rendering.

type PatchFunc = (spec: VgSpec) => VgSpec;

// Patch can be a function, JSON Patch operations, or URL to patch file
patch?: string | PatchFunc | Operation[];

Usage Examples:

// Function-based patching
await embed("#vis", spec, {
  patch: (vgSpec) => {
    vgSpec.width = 400;
    vgSpec.height = 300;
    return vgSpec;
  }
});

// JSON Patch operations
await embed("#vis", spec, {
  patch: [
    { op: "replace", path: "/width", value: 400 },
    { op: "replace", path: "/height", value: 300 }
  ]
});

// Load patches from URL
await embed("#vis", spec, {
  patch: "https://example.com/patches.json"
});

Theming Configuration

Apply pre-built Vega themes to customize appearance.

// Available themes (subset)
type ThemeName = 
  | "dark" 
  | "excel" 
  | "ggplot2" 
  | "googlecharts"
  | "latimes"
  | "quartz"
  | "urbaninstitute"
  | "vox";

await embed("#vis", spec, { theme: "dark" });

Rendering Configuration

Configure the rendering backend and output options.

// Canvas rendering (default)
await embed("#vis", spec, { renderer: "canvas" });

// SVG rendering
await embed("#vis", spec, { renderer: "svg" });

// Custom scale factors for exports
await embed("#vis", spec, {
  scaleFactor: { svg: 2, png: 3 }
});

Install with Tessl CLI