0
# Vue Flow MiniMap
1

2
Vue Flow MiniMap is a Vue 3 component that provides a bird's-eye view of large flow diagrams, enabling users to navigate complex node graphs efficiently. It displays a scaled-down representation of the entire flow with a viewport indicator showing the currently visible area, supporting both visual overview and direct navigation through clicking or dragging within the minimap.
3

4
## Package Information
5

6
- **Package Name**: @vue-flow/minimap
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @vue-flow/minimap`
10

11
## Core Imports
12

13
```typescript
14
import { MiniMap, MiniMapNode } from "@vue-flow/minimap";
15
import type { 
16
  MiniMapProps, MiniMapNodeProps, MiniMapEmits, MiniMapNodeEmits,
17
  MiniMapSlots, MiniMapNodeFunc, ShapeRendering 
18
} from "@vue-flow/minimap";
19
```
20

21
For CommonJS:
22

23
```javascript
24
const { MiniMap, MiniMapNode } = require("@vue-flow/minimap");
25
```
26

27
## Basic Usage
28

29
```vue
30
<script setup>
31
import { VueFlow } from '@vue-flow/core'
32
import { MiniMap } from '@vue-flow/minimap'
33

34
// Import default minimap styles
35
import '@vue-flow/minimap/dist/style.css'
36

37
const elements = ref([
38
  { id: '1', type: 'input', data: { label: 'Node 1' }, position: { x: 100, y: 100 } },
39
  { id: '2', data: { label: 'Node 2' }, position: { x: 300, y: 200 } },
40
])
41
</script>
42

43
<template>
44
  <VueFlow v-model="elements" class="vue-flow-basic-example">
45
    <MiniMap 
46
      :nodeColor="'#e2e2e2'"
47
      :nodeStrokeColor="'transparent'"
48
      :pannable="true"
49
      :zoomable="true"
50
      position="bottom-right"
51
    />
52
  </VueFlow>
53
</template>
54
```
55

56
## Architecture
57

58
Vue Flow MiniMap is built around several key components:
59

60
- **MiniMap Component**: Main minimap component that renders the overview and handles user interactions
61
- **MiniMapNode Component**: Individual node representation within the minimap, supports custom rendering via slots
62
- **D3 Integration**: Uses d3-zoom and d3-selection for smooth pan/zoom interactions
63
- **Vue Flow Integration**: Connects to Vue Flow's core state management and viewport system
64
- **Responsive Design**: Automatically scales and positions based on the flow's bounding box
65

66
## Capabilities
67

68
### MiniMap Component
69

70
Main Vue component that renders the minimap overview with navigation capabilities.
71

72
```typescript { .api }
73
/**
74
 * Vue Flow minimap component providing overview and navigation
75
 */
76
interface MiniMapComponent {
77
  props: MiniMapProps;
78
  emits: MiniMapEmits;
79
  slots: MiniMapSlots;
80
}
81

82
interface MiniMapProps {
83
  /** Node color, can be either a string or a string func that receives the current node */
84
  nodeColor?: string | MiniMapNodeFunc;
85
  /** Node stroke color, can be either a string or a string func that receives the current node */
86
  nodeStrokeColor?: string | MiniMapNodeFunc;
87
  /** Additional node class name, can be either a string or a string func that receives the current node */
88
  nodeClassName?: string | MiniMapNodeFunc;
89
  /** Node border radius */
90
  nodeBorderRadius?: number;
91
  /** Node stroke width */
92
  nodeStrokeWidth?: number;
93
  /** Background color of minimap mask */
94
  maskColor?: string;
95
  /** Border color of minimap mask */
96
  maskStrokeColor?: string;
97
  /** Border width of minimap mask */
98
  maskStrokeWidth?: number;
99
  /** Position of the minimap */
100
  position?: PanelPositionType | PanelPosition;
101
  /** Enable drag minimap to drag viewport */
102
  pannable?: boolean;
103
  /** Enable zoom minimap to zoom viewport */
104
  zoomable?: boolean;
105
  /** Width of minimap */
106
  width?: number;
107
  /** Height of minimap */
108
  height?: number;
109
  /** ARIA label for accessibility */
110
  ariaLabel?: string | null;
111
  /** Enable inverse panning, i.e. drag minimap to move viewport in opposite direction */
112
  inversePan?: boolean;
113
  /** Specify zoom step */
114
  zoomStep?: number;
115
  /** Specify minimap scale */
116
  offsetScale?: number;
117
  /** Mask border radius */
118
  maskBorderRadius?: number;
119
}
120

121
interface MiniMapEmits {
122
  /** Emitted when minimap is clicked */
123
  (event: 'click', params: { event: MouseEvent; position: { x: number; y: number } }): void;
124
  /** Emitted when a node in the minimap is clicked */
125
  (event: 'nodeClick', params: NodeMouseEvent): void;
126
  /** Emitted when a node in the minimap is double-clicked */
127
  (event: 'nodeDblclick', params: NodeMouseEvent): void;
128
  /** Emitted when mouse enters a node in the minimap */
129
  (event: 'nodeMouseenter', params: NodeMouseEvent): void;
130
  /** Emitted when mouse moves over a node in the minimap */
131
  (event: 'nodeMousemove', params: NodeMouseEvent): void;
132
  /** Emitted when mouse leaves a node in the minimap */
133
  (event: 'nodeMouseleave', params: NodeMouseEvent): void;
134
}
135

136
interface MiniMapSlots extends Record<`node-${string}`, (nodeProps: MiniMapNodeProps) => any> {}
137
```
138

139
**Default Values:**
140

141
```typescript
142
// Default prop values from the component
143
const defaultProps = {
144
  nodeColor: '#e2e2e2',
145
  nodeStrokeColor: 'transparent',
146
  nodeBorderRadius: 5,
147
  nodeStrokeWidth: 2,
148
  maskColor: 'rgb(240, 240, 240, 0.6)',
149
  position: 'bottom-right',
150
  maskStrokeColor: 'none',
151
  maskStrokeWidth: 1,
152
  maskBorderRadius: 0,
153
  pannable: false,
154
  zoomable: false,
155
  ariaLabel: 'Vue Flow mini map',
156
  inversePan: false,
157
  zoomStep: 1,
158
  offsetScale: 5
159
};
160
```
161

162
**Usage Examples:**
163

164
```vue
165
<!-- Basic minimap -->
166
<MiniMap />
167

168
<!-- Customized minimap with styling -->
169
<MiniMap 
170
  :nodeColor="(node) => node.selected ? '#ff6b6b' : '#e2e2e2'"
171
  :nodeStrokeColor="'#333'"
172
  :nodeStrokeWidth="2"
173
  :nodeBorderRadius="8"
174
  :maskColor="'rgba(240, 240, 240, 0.8)'"
175
  position="top-left"
176
  :pannable="true"
177
  :zoomable="true"
178
  :width="250"
179
  :height="180"
180
/>
181

182
<!-- With event handlers -->
183
<MiniMap 
184
  @nodeClick="handleNodeClick"
185
  @click="handleMinimapClick"
186
/>
187
```
188

189
### MiniMapNode Component
190

191
Individual node representation within the minimap, supports custom rendering via slots.
192

193
```typescript { .api }
194
/**
195
 * Vue component representing individual nodes in the minimap
196
 */
197
interface MiniMapNodeComponent {
198
  props: MiniMapNodeProps;
199
  emits: MiniMapNodeEmits;
200
}
201

202
interface MiniMapNodeProps {
203
  /** Node identifier */
204
  id: string;
205
  /** Node type */
206
  type: string;
207
  /** Whether node is selected */
208
  selected?: boolean;
209
  /** Whether node is being dragged */
210
  dragging?: boolean;
211
  /** Node position coordinates */
212
  position: XYPosition;
213
  /** Node dimensions */
214
  dimensions: Dimensions;
215
  /** Border radius */
216
  borderRadius?: number;
217
  /** Node color */
218
  color?: string;
219
  /** Shape rendering mode */
220
  shapeRendering?: ShapeRendering;
221
  /** Stroke color */
222
  strokeColor?: string;
223
  /** Stroke width */
224
  strokeWidth?: number;
225
  /** Whether node is hidden */
226
  hidden?: boolean;
227
}
228

229
interface MiniMapNodeEmits {
230
  /** Emitted when node is clicked */
231
  (event: 'click', params: MouseEvent): void;
232
  /** Emitted when node is double-clicked */
233
  (event: 'dblclick', params: MouseEvent): void;
234
  /** Emitted when mouse enters node */
235
  (event: 'mouseenter', params: MouseEvent): void;
236
  /** Emitted when mouse moves over node */
237
  (event: 'mousemove', params: MouseEvent): void;
238
  /** Emitted when mouse leaves node */
239
  (event: 'mouseleave', params: MouseEvent): void;
240
}
241
```
242

243
**Usage Examples:**
244

245
```vue
246
<!-- Custom node rendering via slots -->
247
<MiniMap>
248
  <template #node-custom="nodeProps">
249
    <circle
250
      :cx="nodeProps.position.x + nodeProps.dimensions.width / 2"
251
      :cy="nodeProps.position.y + nodeProps.dimensions.height / 2"
252
      :r="Math.min(nodeProps.dimensions.width, nodeProps.dimensions.height) / 2"
253
      :fill="nodeProps.color"
254
      :stroke="nodeProps.strokeColor"
255
      :stroke-width="nodeProps.strokeWidth"
256
    />
257
  </template>
258
</MiniMap>
259
```
260

261
### Node Color Functions
262

263
Functions that determine node colors based on node properties.
264

265
```typescript { .api }
266
/**
267
 * Function that receives a node and returns a color value
268
 */
269
type MiniMapNodeFunc = (node: GraphNode) => string;
270
```
271

272
**Usage Examples:**
273

274
```typescript
275
// Color nodes based on type
276
const nodeColorFunc: MiniMapNodeFunc = (node) => {
277
  switch (node.type) {
278
    case 'input': return '#4CAF50';
279
    case 'output': return '#f44336';
280
    case 'process': return '#2196F3';
281
    default: return '#e2e2e2';
282
  }
283
};
284

285
// Color nodes based on selection state
286
const selectionColorFunc: MiniMapNodeFunc = (node) => 
287
  node.selected ? '#ff6b6b' : '#e2e2e2';
288
```
289

290
## Types
291

292
```typescript { .api }
293
/** Vue Flow core types used by minimap */
294
interface XYPosition {
295
  x: number;
296
  y: number;
297
}
298

299
interface Dimensions {
300
  width: number;
301
  height: number;
302
}
303

304
interface GraphNode {
305
  id: string;
306
  type: string;
307
  selected?: boolean;
308
  dragging?: boolean;
309
  hidden?: boolean;
310
  position: XYPosition;
311
  dimensions: Dimensions;
312
  style?: CSSProperties;
313
  data?: any;
314
}
315

316
interface NodeMouseEvent {
317
  event: MouseEvent;
318
  node: GraphNode;
319
  connectedEdges: Edge[];
320
}
321

322
interface Edge<Data = any, CustomEvents = any, Type extends string = string> {
323
  /** Unique edge id */
324
  id: string;
325
  /** Edge source node id */
326
  source: string;
327
  /** Edge target node id */
328
  target: string;
329
  /** Source handle id */
330
  sourceHandle?: string | null;
331
  /** Target handle id */
332
  targetHandle?: string | null;
333
  /** Edge type */
334
  type?: Type;
335
  /** Edge label */
336
  label?: string;
337
  /** Animated edge */
338
  animated?: boolean;
339
  /** Whether edge is selected */
340
  selected?: boolean;
341
  /** Whether edge is hidden */
342
  hidden?: boolean;
343
  /** Additional edge data */
344
  data?: Data;
345
}
346

347
/** Panel positioning types */
348
type PanelPositionType = 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
349

350
interface PanelPosition {
351
  x: number;
352
  y: number;
353
}
354

355
/** SVG shape rendering mode */
356
type ShapeRendering = CSSProperties['shapeRendering'];
357

358
/** Vue injection key for minimap slots */
359
const Slots: InjectionKey<MiniMapSlots>;
360
```
361

362
## CSS Styling
363

364
The minimap includes default CSS classes for styling:
365

366
```css
367
/* Import default styles */
368
@import '@vue-flow/minimap/dist/style.css';
369

370
/* Available CSS classes */
371
.vue-flow__minimap {
372
  /* Main minimap container */
373
}
374

375
.vue-flow__minimap.pannable {
376
  /* Minimap when pannable is enabled */
377
  cursor: grab;
378
}
379

380
.vue-flow__minimap.zoomable {
381
  /* Minimap when zoomable is enabled */
382
}
383

384
.vue-flow__minimap-node {
385
  /* Individual minimap node */
386
}
387

388
.vue-flow__minimap-node.selected {
389
  /* Selected minimap node */
390
}
391

392
.vue-flow__minimap-node.dragging {
393
  /* Dragging minimap node */
394
}
395

396
.vue-flow__minimap-mask {
397
  /* Viewport mask overlay */
398
}
399
```
400

401
## Error Handling
402

403
The minimap component handles common edge cases gracefully:
404

405
- **No nodes**: Displays empty minimap when no nodes are present
406
- **Hidden nodes**: Automatically excludes hidden nodes from minimap calculations
407
- **Zero dimensions**: Skips rendering nodes with zero width or height
408
- **Invalid positions**: Uses fallback positioning for nodes with invalid coordinates
409

410
## Browser Compatibility
411

412
- **Chrome/Chromium**: Full support, automatically uses `crispEdges` shape rendering for optimal performance
413
- **Firefox/Safari**: Full support, automatically uses `geometricPrecision` shape rendering for better quality
414
- **IE/Edge Legacy**: Requires Vue 3 compatibility mode
415
- **Mobile browsers**: Touch interaction support for pan and zoom gestures
416

417
**Shape Rendering**: The component automatically selects the optimal shape rendering mode based on the browser:
418
- Chrome-based browsers: `crispEdges` for sharp, pixelated rendering
419
- Other browsers: `geometricPrecision` for smooth, anti-aliased rendering