0
# Actions and Interactions
1

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

4
## Capabilities
5

6
### Actions Interface
7

8
Configuration for the action menu that appears with visualizations.
9

10
```typescript { .api }
11
interface Actions {
12
  /** Enable export actions for downloading visualizations */
13
  export?: boolean | { svg?: boolean; png?: boolean };
14
  
15
  /** Enable "View Source" action to display the original specification */
16
  source?: boolean;
17
  
18
  /** Enable "View Compiled Vega" action to show the compiled Vega spec */
19
  compiled?: boolean;
20
  
21
  /** Enable "Open in Vega Editor" action for external editing */
22
  editor?: boolean;
23
}
24
```
25

26
**Usage Examples:**
27

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

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

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

37
// Selective action configuration
38
await embed("#vis", spec, {
39
  actions: {
40
    export: true,
41
    source: false,
42
    compiled: true,
43
    editor: false
44
  }
45
});
46
```
47

48
### Default Actions Configuration
49

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

52
```typescript { .api }
53
const DEFAULT_ACTIONS: Actions = {
54
  export: { svg: true, png: true },
55
  source: true,
56
  compiled: true,
57
  editor: true
58
};
59
```
60

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

63
### Export Actions
64

65
Configure download functionality for saving visualizations as image files.
66

67
```typescript { .api }
68
export?: boolean | { svg?: boolean; png?: boolean };
69
```
70

71
**Usage Examples:**
72

73
```typescript
74
// Enable all export formats
75
await embed("#vis", spec, { actions: { export: true } });
76

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

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

87
// Custom download filename
88
await embed("#vis", spec, {
89
  actions: { export: true },
90
  downloadFileName: "my-chart"
91
});
92
```
93

94
### Source Viewing
95

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

98
```typescript { .api }
99
source?: boolean;
100
```
101

102
**Usage Examples:**
103

104
```typescript
105
// Enable source viewing
106
await embed("#vis", spec, { actions: { source: true } });
107

108
// Customize source view with header/footer
109
await embed("#vis", spec, {
110
  actions: { source: true },
111
  sourceHeader: "Custom Header Text",
112
  sourceFooter: "Custom Footer Text"
113
});
114
```
115

116
### Compiled Specification Viewing
117

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

120
```typescript { .api }
121
compiled?: boolean;
122
```
123

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

126
### Editor Integration
127

128
Enable opening visualizations in the Vega Editor for interactive editing.
129

130
```typescript { .api }
131
editor?: boolean;
132
```
133

134
**Usage Examples:**
135

136
```typescript
137
// Enable editor integration
138
await embed("#vis", spec, { actions: { editor: true } });
139

140
// Use custom editor URL
141
await embed("#vis", spec, {
142
  actions: { editor: true },
143
  editorUrl: "https://my-custom-editor.com"
144
});
145
```
146

147
### Internationalization Support
148

149
Customize action menu text for different languages.
150

151
```typescript { .api }
152
interface I18N {
153
  CLICK_TO_VIEW_ACTIONS: string;
154
  COMPILED_ACTION: string;
155
  EDITOR_ACTION: string;
156
  PNG_ACTION: string;
157
  SOURCE_ACTION: string;
158
  SVG_ACTION: string;
159
}
160

161
i18n?: Partial<I18N>;
162
```
163

164
**Usage Examples:**
165

166
```typescript
167
await embed("#vis", spec, {
168
  actions: true,
169
  i18n: {
170
    PNG_ACTION: "Download as PNG",
171
    SVG_ACTION: "Download as SVG",
172
    SOURCE_ACTION: "Show Source Code",
173
    EDITOR_ACTION: "Edit in Vega Editor"
174
  }
175
});
176
```
177

178
### Action Menu Behavior
179

180
Control when and how the actions menu appears.
181

182
```typescript { .api }
183
/** Always show actions menu (even for small charts) */
184
forceActionsMenu?: boolean;
185
```
186

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

189
**Usage Examples:**
190

191
```typescript
192
// Force actions menu to always appear
193
await embed("#vis", spec, {
194
  actions: true,
195
  forceActionsMenu: true
196
});
197
```
198

199
### Action Menu Styling
200

201
The actions menu can be styled using CSS classes:
202

203
```css
204
.vega-actions {
205
  /* Style the actions container */
206
}
207

208
.vega-actions a {
209
  /* Style individual action links */
210
}
211

212
.vega-actions a:hover {
213
  /* Style action links on hover */
214
}
215
```
216

217
### Post Message Integration
218

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

221
```typescript { .api }
222
/**
223
 * Post message to Vega Editor window
224
 * @param window - Window object
225
 * @param url - Editor URL
226
 * @param data - Message data to send
227
 */
228
function post(window: Window, url: string, data: MessageData): void;
229

230
interface MessageData {
231
  spec: string;
232
  file?: unknown;
233
  config?: Config;
234
  mode: Mode;
235
  renderer?: Renderers;
236
}
237
```
238

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