tessl/npm-vega-embed

Publish Vega visualizations as embedded web components.

—

Pending

Overview

Eval results

Files

Actions and Interactions

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

Built-in action menu system providing export functionality, source viewing, and editor integration for enhanced user interaction with visualizations. The actions system allows users to export charts, view specifications, and open charts in external editors.

Capabilities

Actions Interface

Configuration for the action menu that appears with visualizations.

interface Actions {
  /** Enable export actions for downloading visualizations */
  export?: boolean | { svg?: boolean; png?: boolean };
  
  /** Enable "View Source" action to display the original specification */
  source?: boolean;
  
  /** Enable "View Compiled Vega" action to show the compiled Vega spec */
  compiled?: boolean;
  
  /** Enable "Open in Vega Editor" action for external editing */
  editor?: boolean;
}

Usage Examples:

import embed from "vega-embed";

// Enable all actions (default behavior)
await embed("#vis", spec, { actions: true });

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

// Selective action configuration
await embed("#vis", spec, {
  actions: {
    export: true,
    source: false,
    compiled: true,
    editor: false
  }
});

Default Actions Configuration

Pre-configured default actions that are applied when actions are enabled.

const DEFAULT_ACTIONS: Actions = {
  export: { svg: true, png: true },
  source: true,
  compiled: true,
  editor: true
};

All actions are enabled by default, with both SVG and PNG export formats available.

Export Actions

Configure download functionality for saving visualizations as image files.

export?: boolean | { svg?: boolean; png?: boolean };

Usage Examples:

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

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

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

// Custom download filename
await embed("#vis", spec, {
  actions: { export: true },
  downloadFileName: "my-chart"
});

Source Viewing

Enable viewing of the original specification that was provided to the embed function.

source?: boolean;

Usage Examples:

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

// Customize source view with header/footer
await embed("#vis", spec, {
  actions: { source: true },
  sourceHeader: "Custom Header Text",
  sourceFooter: "Custom Footer Text"
});

Compiled Specification Viewing

Enable viewing of the final compiled Vega specification (useful for Vega-Lite specs).

compiled?: boolean;

This action shows the fully compiled and processed Vega specification that is actually rendered, which is particularly useful when working with Vega-Lite specifications.

Editor Integration

Enable opening visualizations in the Vega Editor for interactive editing.

editor?: boolean;

Usage Examples:

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

// Use custom editor URL
await embed("#vis", spec, {
  actions: { editor: true },
  editorUrl: "https://my-custom-editor.com"
});

Internationalization Support

Customize action menu text for different languages.

interface I18N {
  CLICK_TO_VIEW_ACTIONS: string;
  COMPILED_ACTION: string;
  EDITOR_ACTION: string;
  PNG_ACTION: string;
  SOURCE_ACTION: string;
  SVG_ACTION: string;
}

i18n?: Partial<I18N>;

Usage Examples:

await embed("#vis", spec, {
  actions: true,
  i18n: {
    PNG_ACTION: "Download as PNG",
    SVG_ACTION: "Download as SVG",
    SOURCE_ACTION: "Show Source Code",
    EDITOR_ACTION: "Edit in Vega Editor"
  }
});

Action Menu Behavior

Control when and how the actions menu appears.

/** Always show actions menu (even for small charts) */
forceActionsMenu?: boolean;

By default, the actions menu may be hidden for very small visualizations. Use forceActionsMenu: true to always display it.

Usage Examples:

// Force actions menu to always appear
await embed("#vis", spec, {
  actions: true,
  forceActionsMenu: true
});

Action Menu Styling

The actions menu can be styled using CSS classes:

.vega-actions {
  /* Style the actions container */
}

.vega-actions a {
  /* Style individual action links */
}

.vega-actions a:hover {
  /* Style action links on hover */
}

Post Message Integration

The editor integration uses the post message system for communication with external editors.

/**
 * Post message to Vega Editor window
 * @param window - Window object
 * @param url - Editor URL
 * @param data - Message data to send
 */
function post(window: Window, url: string, data: MessageData): void;

interface MessageData {
  spec: string;
  file?: unknown;
  config?: Config;
  mode: Mode;
  renderer?: Renderers;
}

This function handles the communication protocol with external editors when the editor action is used.

Install with Tessl CLI