0
# Vega-Embed
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: vega-embed
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install vega-embed`
10

11
## Core Imports
12

13
```typescript
14
import embed from "vega-embed";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const embed = require("vega-embed");
21
```
22

23
Named imports (access properties on default export):
24

25
```typescript
26
import vegaEmbed from "vega-embed";
27

28
// Access functions and properties
29
vegaEmbed.embed(el, spec, opts);
30
vegaEmbed.container(spec, opts);
31
vegaEmbed.vega;
32
vegaEmbed.vegaLite;
33
vegaEmbed.vl; // backwards compatibility alias for vegaLite
34
vegaEmbed.version;
35
```
36

37
## Basic Usage
38

39
```typescript
40
import embed from "vega-embed";
41

42
// Embed a Vega-Lite specification
43
const spec = {
44
  mark: "bar",
45
  data: { values: [{ a: "A", b: 28 }, { a: "B", b: 55 }] },
46
  encoding: {
47
    x: { field: "a", type: "ordinal" },
48
    y: { field: "b", type: "quantitative" }
49
  }
50
};
51

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

56
## Architecture
57

58
Vega-Embed is built around several key components:
59

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

67
## Capabilities
68

69
### Core Embedding
70

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

73
```typescript { .api }
74
function embed(
75
  el: HTMLElement | string,
76
  spec: VisualizationSpec | string,
77
  opts?: EmbedOptions
78
): Promise<Result>;
79

80
type VisualizationSpec = VlSpec | VgSpec;
81

82
interface Result {
83
  view: View;
84
  spec: VisualizationSpec;
85
  vgSpec: VgSpec;
86
  embedOptions: EmbedOptions;
87
  finalize: () => void;
88
}
89
```
90

91
[Core Embedding](./embedding.md)
92

93
### Container Creation
94

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

97
```typescript { .api }
98
function container(
99
  spec: VisualizationSpec | string,
100
  opt?: EmbedOptions
101
): Promise<HTMLDivElement & { value: View }>;
102
```
103

104
[Container Creation](./container.md)
105

106
### Configuration Options
107

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

110
```typescript { .api }
111
interface EmbedOptions<S = string, R = Renderers> {
112
  bind?: HTMLElement | string;
113
  actions?: boolean | Actions;
114
  mode?: Mode;
115
  theme?: keyof Omit<typeof themes, 'version'>;
116
  defaultStyle?: boolean | string;
117
  renderer?: R;
118
  tooltip?: TooltipHandler | TooltipOptions | boolean;
119
  patch?: S | PatchFunc | Operation[];
120
  width?: number;
121
  height?: number;
122
  config?: S | Config;
123
  // ... additional options
124
}
125
```
126

127
[Configuration Options](./options.md)
128

129
### Actions and Interactions
130

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

133
```typescript { .api }
134
interface Actions {
135
  export?: boolean | { svg?: boolean; png?: boolean };
136
  source?: boolean;
137
  compiled?: boolean;
138
  editor?: boolean;
139
}
140

141
const DEFAULT_ACTIONS: Actions;
142
```
143

144
[Actions and Interactions](./actions.md)
145

146
### Utilities and Helpers
147

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

150
```typescript { .api }
151
function guessMode(spec: VisualizationSpec, providedMode?: Mode): Mode;
152
function isURL(s: string): boolean;
153
function mergeDeep<T>(dest: T, ...src: readonly DeepPartial<T>[]): T;
154

155
type Mode = 'vega' | 'vega-lite';
156
```
157

158
[Utilities and Helpers](./utilities.md)
159

160
## Re-exported Libraries
161

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

164
```typescript { .api }
165
const vega: typeof vegaImport;
166
let vegaLite: typeof vegaLiteImport;
167
const version: string;
168
```
169

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