0
# Configuration Options
1

2
Comprehensive configuration system for customizing visualization rendering, appearance, interactions, and behavior. The EmbedOptions interface provides fine-grained control over all aspects of the embedding process.
3

4
## Capabilities
5

6
### EmbedOptions Interface
7

8
Main configuration interface with extensive customization options.
9

10
```typescript { .api }
11
interface EmbedOptions<S = string, R = Renderers> {
12
  /** Element to bind interactions to (defaults to the visualization element) */
13
  bind?: HTMLElement | string;
14
  
15
  /** Configure action menu buttons (export, source, compiled, editor) */
16
  actions?: boolean | Actions;
17
  
18
  /** Force interpretation as 'vega' or 'vega-lite' (auto-detected if not provided) */
19
  mode?: Mode;
20
  
21
  /** Apply a Vega theme (e.g., 'dark', 'excel', 'ggplot2', 'quartz') */
22
  theme?: keyof Omit<typeof themes, 'version'>;
23
  
24
  /** Include default CSS styling (true by default) */
25
  defaultStyle?: boolean | string;
26
  
27
  /** Set logging level (0=none, 1=warn, 2=info, 3=debug) */
28
  logLevel?: number;
29
  
30
  /** Configure data loading behavior */
31
  loader?: Loader | LoaderOptions;
32
  
33
  /** Rendering backend ('canvas' or 'svg') */
34
  renderer?: R;
35
  
36
  /** Configure tooltip behavior */
37
  tooltip?: TooltipHandler | TooltipOptions | boolean;
38
  
39
  /** Specification patches to apply */
40
  patch?: S | PatchFunc | Operation[];
41
  
42
  /** Override visualization width */
43
  width?: number;
44
  
45
  /** Override visualization height */
46
  height?: number;
47
  
48
  /** Set padding around the visualization */
49
  padding?: number | { left?: number; right?: number; top?: number; bottom?: number };
50
  
51
  /** Scale factor for exports */
52
  scaleFactor?: number | { svg?: number; png?: number };
53
  
54
  /** Vega/Vega-Lite configuration object */
55
  config?: S | Config;
56
  
57
  /** Header text for source view */
58
  sourceHeader?: string;
59
  
60
  /** Footer text for source view */
61
  sourceFooter?: string;
62
  
63
  /** Custom URL for Vega Editor */
64
  editorUrl?: string;
65
  
66
  /** Configure hover interactions */
67
  hover?: boolean | Hover;
68
  
69
  /** Internationalization strings */
70
  i18n?: Partial<typeof I18N>;
71
  
72
  /** Default filename for downloads */
73
  downloadFileName?: string;
74
  
75
  /** Number formatting locale */
76
  formatLocale?: Record<string, unknown>;
77
  
78
  /** Time formatting locale */
79
  timeFormatLocale?: Record<string, unknown>;
80
  
81
  /** Custom expression functions */
82
  expressionFunctions?: ExpressionFunction;
83
  
84
  /** Enable AST parsing mode */
85
  ast?: boolean;
86
  
87
  /** Custom expression interpreter */
88
  expr?: typeof expressionInterpreter;
89
  
90
  /** Custom View class */
91
  viewClass?: typeof View;
92
  
93
  /** Always show actions menu (even for small charts) */
94
  forceActionsMenu?: boolean;
95
}
96
```
97

98
### Actions Configuration
99

100
Configure the action menu buttons that appear with visualizations.
101

102
```typescript { .api }
103
interface Actions {
104
  /** Enable export actions (PNG/SVG download) */
105
  export?: boolean | { svg?: boolean; png?: boolean };
106
  
107
  /** Enable "View Source" action */
108
  source?: boolean;
109
  
110
  /** Enable "View Compiled Vega" action */
111
  compiled?: boolean;
112
  
113
  /** Enable "Open in Vega Editor" action */
114
  editor?: boolean;
115
}
116

117
/** Default actions configuration */
118
const DEFAULT_ACTIONS: Actions = {
119
  export: { svg: true, png: true },
120
  source: true,
121
  compiled: true,
122
  editor: true
123
};
124
```
125

126
**Usage Examples:**
127

128
```typescript
129
// Disable all actions
130
await embed("#vis", spec, { actions: false });
131

132
// Enable only export
133
await embed("#vis", spec, { actions: { export: true } });
134

135
// Customize export formats
136
await embed("#vis", spec, {
137
  actions: {
138
    export: { svg: true, png: false },
139
    source: true,
140
    compiled: false,
141
    editor: false
142
  }
143
});
144
```
145

146
### Hover Configuration
147

148
Configure hover interactions and visual feedback.
149

150
```typescript { .api }
151
interface Hover {
152
  /** Encoding set name for hover highlighting */
153
  hoverSet?: EncodeEntryName;
154
  
155
  /** Encoding set name for updates */
156
  updateSet?: EncodeEntryName;
157
}
158
```
159

160
**Usage Examples:**
161

162
```typescript
163
// Enable hover interactions
164
await embed("#vis", spec, { hover: true });
165

166
// Custom hover configuration
167
await embed("#vis", spec, {
168
  hover: {
169
    hoverSet: "hover",
170
    updateSet: "update"
171
  }
172
});
173
```
174

175
### Patching Configuration
176

177
Support for dynamically modifying specifications before rendering.
178

179
```typescript { .api }
180
type PatchFunc = (spec: VgSpec) => VgSpec;
181

182
// Patch can be a function, JSON Patch operations, or URL to patch file
183
patch?: string | PatchFunc | Operation[];
184
```
185

186
**Usage Examples:**
187

188
```typescript
189
// Function-based patching
190
await embed("#vis", spec, {
191
  patch: (vgSpec) => {
192
    vgSpec.width = 400;
193
    vgSpec.height = 300;
194
    return vgSpec;
195
  }
196
});
197

198
// JSON Patch operations
199
await embed("#vis", spec, {
200
  patch: [
201
    { op: "replace", path: "/width", value: 400 },
202
    { op: "replace", path: "/height", value: 300 }
203
  ]
204
});
205

206
// Load patches from URL
207
await embed("#vis", spec, {
208
  patch: "https://example.com/patches.json"
209
});
210
```
211

212
### Theming Configuration
213

214
Apply pre-built Vega themes to customize appearance.
215

216
```typescript
217
// Available themes (subset)
218
type ThemeName = 
219
  | "dark" 
220
  | "excel" 
221
  | "ggplot2" 
222
  | "googlecharts"
223
  | "latimes"
224
  | "quartz"
225
  | "urbaninstitute"
226
  | "vox";
227

228
await embed("#vis", spec, { theme: "dark" });
229
```
230

231
### Rendering Configuration
232

233
Configure the rendering backend and output options.
234

235
```typescript
236
// Canvas rendering (default)
237
await embed("#vis", spec, { renderer: "canvas" });
238

239
// SVG rendering
240
await embed("#vis", spec, { renderer: "svg" });
241

242
// Custom scale factors for exports
243
await embed("#vis", spec, {
244
  scaleFactor: { svg: 2, png: 3 }
245
});
246
```