0
# Container Creation
1

2
Specialized function for creating standalone visualization containers with embedded views. The container function is optimized for Observable and interactive environments where you need a self-contained div element with the visualization.
3

4
## Capabilities
5

6
### Container Function
7

8
Creates an HTML div element with an embedded Vega-Lite or Vega visualization, with the view accessible as the `value` property.
9

10
```typescript { .api }
11
/**
12
 * Create a container div with embedded Vega/Vega-Lite visualization
13
 * @param spec - Vega/Vega-Lite specification as object or URL string
14
 * @param opt - Optional configuration options
15
 * @returns Promise resolving to HTMLDivElement with value property containing the view
16
 */
17
function container(
18
  spec: VisualizationSpec | string,
19
  opt?: EmbedOptions
20
): Promise<HTMLDivElement & { value: View }>;
21
```
22

23
**Usage Examples:**
24

25
```typescript
26
import { container } from "vega-embed";
27

28
// Create container with default options
29
const wrapper = await container(spec);
30
document.body.appendChild(wrapper);
31

32
// Access the view through the value property
33
console.log(wrapper.value); // View instance
34

35
// Create container with custom options
36
const wrapper = await container(spec, {
37
  actions: { export: true, source: false, compiled: true, editor: true },
38
  renderer: "svg"
39
});
40
```
41

42
### Observable Integration
43

44
The container function is specifically designed for Observable notebooks where the return value needs to be a DOM element:
45

46
```typescript
47
// In Observable
48
viewof myChart = {
49
  const wrapper = await embed.container(spec, options);
50
  return wrapper;
51
}
52

53
// Access the view in other cells
54
myChart // This is the View instance
55
```
56

57
### Default Action Configuration
58

59
By default, the container function enables most actions except for the source action, making it suitable for interactive environments:
60

61
```typescript
62
// Default actions for container function
63
const defaultActions = {
64
  export: true,
65
  source: false,
66
  compiled: true,
67
  editor: true
68
};
69
```
70

71
### Container Structure
72

73
The returned container has a specific DOM structure:
74

75
```html
76
<div class="vega-embed-wrapper">
77
  <div>
78
    <!-- Vega visualization content -->
79
  </div>
80
</div>
81
```
82

83
**Usage Examples:**
84

85
```typescript
86
const wrapper = await container(spec);
87

88
// The wrapper has CSS class for styling
89
console.log(wrapper.classList.contains('vega-embed-wrapper')); // true
90

91
// The visualization is in the first child
92
const vizElement = wrapper.firstElementChild;
93

94
// The view is accessible via the value property
95
const view = wrapper.value;
96
```
97

98
### Differences from Embed Function
99

100
Key differences between `container` and `embed`:
101

102
- **Return Type**: Returns a div element vs Promise&lt;Result&gt;
103
- **DOM Integration**: Creates its own container vs requiring existing element
104
- **Observable Optimized**: Designed for notebook environments
105
- **Default Actions**: Different default action configuration
106
- **Value Property**: View accessible via `.value` property
107

108
```typescript
109
// container() - creates its own element
110
const wrapper = await container(spec);
111
document.body.appendChild(wrapper);
112

113
// embed() - uses existing element
114
const result = await embed("#existing-div", spec);
115
```