0
# Core Embedding
1

2
Main embedding functionality for integrating Vega and Vega-Lite visualizations into web applications. The embed function handles spec loading from URLs or objects, automatic mode detection, and comprehensive configuration options.
3

4
## Capabilities
5

6
### Embed Function
7

8
Primary function for embedding Vega/Vega-Lite visualizations into DOM elements.
9

10
```typescript { .api }
11
/**
12
 * Embed a Vega or Vega-Lite visualization into a DOM element
13
 * @param el - DOM element or CSS selector string indicating where to embed
14
 * @param spec - Vega/Vega-Lite specification as object or URL string
15
 * @param opts - Optional configuration options
16
 * @returns Promise resolving to Result object with view instance and metadata
17
 */
18
function embed(
19
  el: HTMLElement | string,
20
  spec: VisualizationSpec | string,
21
  opts?: EmbedOptions
22
): Promise<Result>;
23
```
24

25
**Usage Examples:**
26

27
```typescript
28
import embed from "vega-embed";
29

30
// Embed with DOM element
31
const element = document.getElementById("vis");
32
const result = await embed(element, spec);
33

34
// Embed with CSS selector
35
const result = await embed("#vis", spec);
36

37
// Embed with options
38
const result = await embed("#vis", spec, {
39
  renderer: "svg",
40
  actions: false,
41
  theme: "dark"
42
});
43

44
// Load spec from URL
45
const result = await embed("#vis", "https://example.com/chart.json");
46
```
47

48
### Result Object
49

50
The embed function returns a comprehensive result object containing the view instance and metadata.
51

52
```typescript { .api }
53
interface Result {
54
  /** The instantiated Vega view instance */
55
  view: View;
56
  /** Copy of the input specification */
57
  spec: VisualizationSpec;
58
  /** The compiled and patched Vega specification */
59
  vgSpec: VgSpec;
60
  /** The embed options that were used */
61
  embedOptions: EmbedOptions;
62
  /** Cleanup function to prevent memory leaks */
63
  finalize: () => void;
64
}
65
```
66

67
**Usage Examples:**
68

69
```typescript
70
const result = await embed("#vis", spec);
71

72
// Access the Vega view for interactions
73
result.view.addEventListener('click', (event, item) => {
74
  console.log('Clicked:', item);
75
});
76

77
// Get the final compiled spec
78
console.log(result.vgSpec);
79

80
// Clean up when done
81
result.finalize();
82
```
83

84
### Visualization Specifications
85

86
Union type supporting both Vega and Vega-Lite specifications.
87

88
```typescript { .api }
89
type VisualizationSpec = VlSpec | VgSpec;
90
```
91

92
The embed function automatically detects the specification format and handles compilation as needed. Vega-Lite specs are compiled to Vega specs internally.
93

94
### Error Handling
95

96
The embed function is async and may throw errors for various conditions:
97

98
```typescript
99
try {
100
  const result = await embed("#vis", spec);
101
} catch (error) {
102
  console.error("Embedding failed:", error);
103
}
104
```
105

106
Common error scenarios:
107
- Invalid specification format
108
- Network errors when loading specs from URLs
109
- Missing DOM element
110
- Compilation errors in Vega-Lite specs