From 90891cd568b3137558598884254dbdf2197a36ee Mon Sep 17 00:00:00 2001
From: Justineo <justice360@gmail.com>
Date: Fri, 5 Sep 2025 13:19:59 +0800
Subject: [PATCH] feat(controls): add slot props, add `control-item` slot for
 controls

---
 docs/src/guide/components/controls.md       |  67 ++++++++---
 examples/vite/router.ts                     |   4 +
 examples/vite/src/Controls/ControlsSlot.vue |  69 +++++++++++
 packages/controls/README.md                 |   1 -
 packages/controls/package.json              |  20 +--
 packages/controls/src/Controls.vue          | 127 +++++++++++++++-----
 packages/controls/src/svg.d.ts              |   8 ++
 packages/controls/src/types.ts              |  43 +++++++
 packages/controls/tsconfig.json             |  11 +-
 9 files changed, 282 insertions(+), 68 deletions(-)
 create mode 100644 examples/vite/src/Controls/ControlsSlot.vue
 create mode 100644 packages/controls/src/svg.d.ts

diff --git a/docs/src/guide/components/controls.md b/docs/src/guide/components/controls.md
index 80ecafb36..e53b37f19 100644
--- a/docs/src/guide/components/controls.md
+++ b/docs/src/guide/components/controls.md
@@ -35,15 +35,51 @@ import '@vue-flow/controls/dist/style.css'
 </template>
 ```
 
+You can also customize the controls by using the provided slots and slot props.
+
+```vue
+<script setup>
+import { VueFlow } from '@vue-flow/core'
+import type { ControlType } from '@vue-flow/controls'
+import { ControlButton, Controls } from '@vue-flow/controls'
+
+// import default controls styles
+import '@vue-flow/controls/dist/style.css'
+
+// import custom tooltip component
+import Tooltip from './Tooltip.vue'
+
+const tooltips: Record<ControlType, string> = {
+  'zoom-in': 'Zoom In',
+  'zoom-out': 'Zoom Out',
+  'fit-view': 'Fit View',
+  'interactive': 'Lock/Unlock Interaction',
+}
+</script>
+
+<template>
+  <VueFlow>
+    <Controls>
+      <template #control-item="{ control, onClick, icon }">
+        <Tooltip :text="tooltips[control]">
+          <ControlButton @click="onClick">
+            <component :is="icon" />
+          </ControlButton>
+        </Tooltip>
+      </template>
+    </Controls>
+  </VueFlow>
+</template>
+```
 
 ## [Props](/typedocs/interfaces/ControlProps)
 
-| Name            | Definition                             | Type                                           | Optional | Default |
-|-----------------|----------------------------------------|------------------------------------------------|----------|---------|
-| showZoom        | Show zoom btn                          | boolean                                        | true     | true    |
-| showFitView     | Show fit-view btn                      | boolean                                        | true     | true    |
-| showInteractive | Show lock interactive btn              | boolean                                        | true     | true    |
-| showZoom        | Show zoom button                       | boolean                                        | true     | true    |
+| Name            | Definition                             | Type                                                  | Optional | Default |
+|-----------------|----------------------------------------|-------------------------------------------------------|----------|---------|
+| showZoom        | Show zoom btn                          | boolean                                               | true     | true    |
+| showFitView     | Show fit-view btn                      | boolean                                               | true     | true    |
+| showInteractive | Show lock interactive btn              | boolean                                               | true     | true    |
+| showZoom        | Show zoom button                       | boolean                                               | true     | true    |
 | fitViewParams   | Params to use on fit-view button click | [FitViewParams](/typedocs/type-aliases/FitViewParams) | true     | -       |
 
 ## Emits
@@ -59,14 +95,15 @@ import '@vue-flow/controls/dist/style.css'
 
 ### Control Buttons
 
-| Name                | Definition                 |
-|---------------------|----------------------------|
-| top                 | Slot above default buttons |
-| control-zoom-in     | Zoom-in btn                |
-| control-zoom-out    | Zoom-out btn               |
-| control-fit-view    | Fit-view btn               |
-| control-interactive | Interaction btn            |
-| default             | Slot below default buttons |
+| Name                | Definition                 | Props                                                                                                                |
+|---------------------|----------------------------|----------------------------------------------------------------------------------------------------------------------|
+| top                 | Slot above default buttons | [ControlsSlotProps](/typedocs/interfaces/ControlsSlotProps)                                                          |
+| control-item        | Each control btn           | [ControlItemSlotProps](/typedocs/interfaces/ControlItemSlotProps)                                                    |
+| control-zoom-in     | Zoom-in btn                | { disabled: boolean; zoomIn: () \=> any; icon: Component }                                                           |
+| control-zoom-out    | Zoom-out btn               | { disabled: boolean; zoomOut: () \=> any; icon: Component }                                                          |
+| control-fit-view    | Fit-view btn               | { fitView: () \=> any; icon: Component }                                                                             |
+| control-interactive | Interaction btn            | { interactive: boolean; toggleInteractive: () \=> any; icon: Component; lockIcon: Component; unlockIcon: Component } |
+| default             | Slot below default buttons | [ControlsSlotProps](/typedocs/interfaces/ControlsSlotProps)                                                          |
 
 ### Icons
 
@@ -77,5 +114,3 @@ import '@vue-flow/controls/dist/style.css'
 | icon-fit-view | Fit-view icon             |
 | icon-lock     | Interaction locked icon   |
 | icon-unlock   | Interaction unlocked icon |
-
-
diff --git a/examples/vite/router.ts b/examples/vite/router.ts
index a1f4180b3..20c680b58 100644
--- a/examples/vite/router.ts
+++ b/examples/vite/router.ts
@@ -138,6 +138,10 @@ export const routes: RouterOptions['routes'] = [
     path: '/confirm-delete',
     component: () => import('./src/ConfirmDelete/ConfirmDeleteExample.vue'),
   },
+  {
+    path: '/controls-slot',
+    component: () => import('./src/Controls/ControlsSlot.vue'),
+  },
 ]
 
 export const router = createRouter({
diff --git a/examples/vite/src/Controls/ControlsSlot.vue b/examples/vite/src/Controls/ControlsSlot.vue
new file mode 100644
index 000000000..7019ed51a
--- /dev/null
+++ b/examples/vite/src/Controls/ControlsSlot.vue
@@ -0,0 +1,69 @@
+<script lang="ts" setup>
+import type { Node } from '@vue-flow/core'
+import { VueFlow } from '@vue-flow/core'
+
+import { Background } from '@vue-flow/background'
+import type { ControlType } from '@vue-flow/controls'
+import { Controls } from '@vue-flow/controls'
+
+const nodes = ref<Node[]>([
+  { id: '1', type: 'input', label: 'Node 1', position: { x: 250, y: 5 }, class: 'light' },
+  { id: '2', label: 'Node 2', position: { x: 100, y: 100 }, class: 'light' },
+  { id: '3', label: 'Node 3', position: { x: 400, y: 100 }, class: 'light' },
+  { id: '4', label: 'Node 4', position: { x: 400, y: 200 }, class: 'light' },
+])
+
+const tooltips: Record<ControlType, string> = {
+  'zoom-in': 'Zoom In',
+  'zoom-out': 'Zoom Out',
+  'fit-view': 'Fit View',
+  'interactive': 'Lock/Unlock Interaction',
+}
+</script>
+
+<template>
+  <VueFlow :nodes="nodes" fit-view-on-init class="vue-flow-controls-example">
+    <Background />
+    <Controls>
+      <template #control-item="{ control, disabled, onClick, icon }">
+        <button class="control" :title="tooltips[control]" :disabled="disabled" @click="onClick">
+          <component :is="icon" class="icon" />
+        </button>
+      </template>
+
+      <template #control-interactive="{ interactive, toggleInteractive }">
+        <button class="control" :title="interactive ? 'Lock' : 'Unock'" @click="toggleInteractive">
+          {{ interactive ? '🔓' : '🔒' }}
+        </button>
+      </template>
+    </Controls>
+  </VueFlow>
+</template>
+
+<style scoped>
+.control {
+  width: 32px;
+  height: 32px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border: none;
+  background: #fafafa;
+  cursor: pointer;
+}
+
+.control:not(:disabled):hover {
+  background: #eee;
+}
+
+.control:disabled {
+  cursor: not-allowed;
+  color: #ccc;
+}
+
+.icon {
+  fill: currentColor;
+  width: 16px;
+  height: 16px;
+}
+</style>
diff --git a/packages/controls/README.md b/packages/controls/README.md
index 4cac4d97d..5b9f3041f 100644
--- a/packages/controls/README.md
+++ b/packages/controls/README.md
@@ -25,7 +25,6 @@ import '@vue-flow/controls/dist/style.css'
 
 import initialElements from './initial-elements'
 
-
 // some nodes and edges
 const elements = ref(initialElements)
 </script>
diff --git a/packages/controls/package.json b/packages/controls/package.json
index cc008dac0..b1e5b48b5 100644
--- a/packages/controls/package.json
+++ b/packages/controls/package.json
@@ -2,13 +2,13 @@
   "name": "@vue-flow/controls",
   "version": "1.1.3",
   "private": false,
-  "license": "MIT",
   "author": "Burak Cakmakoglu<78412429+bcakmakoglu@users.noreply.github.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/bcakmakoglu/vue-flow#readme",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/bcakmakoglu/vue-flow/packages/plugins/controls"
   },
-  "homepage": "https://github.com/bcakmakoglu/vue-flow#readme",
   "bugs": {
     "url": "https://github.com/bcakmakoglu/vue-flow/issues"
   },
@@ -28,11 +28,9 @@
     "vueflow",
     "typescript"
   ],
-  "main": "./dist/vue-flow-controls.js",
-  "module": "./dist/vue-flow-controls.mjs",
-  "types": "./dist/index.d.ts",
-  "unpkg": "./dist/vue-flow-controls.iife.js",
-  "jsdelivr": "./dist/vue-flow-controls.iife.js",
+  "sideEffects": [
+    "*.css"
+  ],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -41,13 +39,15 @@
     },
     "./dist/style.css": "./dist/style.css"
   },
+  "main": "./dist/vue-flow-controls.js",
+  "module": "./dist/vue-flow-controls.mjs",
+  "unpkg": "./dist/vue-flow-controls.iife.js",
+  "jsdelivr": "./dist/vue-flow-controls.iife.js",
+  "types": "./dist/index.d.ts",
   "files": [
     "dist",
     "*.d.ts"
   ],
-  "sideEffects": [
-    "*.css"
-  ],
   "scripts": {
     "dev": "pnpm types:watch & pnpm build:watch",
     "build": "vite build",
diff --git a/packages/controls/src/Controls.vue b/packages/controls/src/Controls.vue
index 15c3b97f2..77445ebc1 100644
--- a/packages/controls/src/Controls.vue
+++ b/packages/controls/src/Controls.vue
@@ -1,7 +1,8 @@
 <script lang="ts" setup>
-import { Panel, PanelPosition, useVueFlow } from '@vue-flow/core'
-import { toRef } from 'vue'
-import type { ControlProps } from './types'
+import { Panel, useVueFlow } from '@vue-flow/core'
+import type { Component } from 'vue'
+import { computed, toRef } from 'vue'
+import type { ControlItemSlotProps, ControlProps, ControlsSlotProps } from './types'
 import ControlButton from './ControlButton.vue'
 import PlusIcon from './icons/plus.svg'
 import MinusIcon from './icons/minus.svg'
@@ -14,7 +15,7 @@ const {
   showFitView = true,
   showInteractive = true,
   fitViewParams,
-  position = PanelPosition.BottomLeft,
+  position = 'bottom-left',
 } = defineProps<ControlProps>()
 
 const emit = defineEmits<{
@@ -24,6 +25,27 @@ const emit = defineEmits<{
   (event: 'interactionChange', active: boolean): void
 }>()
 
+defineSlots<{
+  default(props: ControlsSlotProps): any
+  top(props: ControlsSlotProps): any
+  'control-item'(props: ControlItemSlotProps): any
+  'control-zoom-in'(props: { disabled: boolean; zoomIn: () => any; icon: Component }): any
+  'control-zoom-out'(props: { disabled: boolean; zoomOut: () => any; icon: Component }): any
+  'control-fit-view'(props: { fitView: () => any; icon: Component }): any
+  'control-interactive'(props: {
+    interactive: boolean
+    toggleInteractive: () => any
+    icon: Component
+    lockIcon: Component
+    unlockIcon: Component
+  }): any
+  'icon-zoom-in'(props: {}): any
+  'icon-zoom-out'(props: {}): any
+  'icon-fit-view'(props: {}): any
+  'icon-lock'(props: {}): any
+  'icon-unlock'(props: {}): any
+}>()
+
 const {
   nodesDraggable,
   nodesConnectable,
@@ -66,6 +88,25 @@ function onInteractiveChangeHandler() {
 
   emit('interactionChange', !isInteractive.value)
 }
+
+const slotProps = computed(
+  () =>
+    ({
+      zoomInDisabled: maxZoomReached.value,
+      zoomIn: onZoomInHandler,
+      zoomInIcon: PlusIcon,
+      zoomOutDisabled: minZoomReached.value,
+      zoomOut: onZoomOutHandler,
+      zoomOutIcon: MinusIcon,
+      fitView: onFitViewHandler,
+      fitViewIcon: FitView,
+      interactive: isInteractive.value,
+      toggleInteractive: onInteractiveChangeHandler,
+      interactiveIcon: isInteractive.value ? Unlock : Lock,
+      lockIcon: Lock,
+      unlockIcon: Unlock,
+    } satisfies ControlsSlotProps),
+)
 </script>
 
 <script lang="ts">
@@ -77,49 +118,69 @@ export default {
 
 <template>
   <Panel class="vue-flow__controls" :position="position">
-    <slot name="top" />
+    <slot name="top" v-bind="slotProps" />
 
     <template v-if="showZoom">
-      <slot name="control-zoom-in">
-        <ControlButton class="vue-flow__controls-zoomin" :disabled="maxZoomReached" @click="onZoomInHandler">
-          <slot name="icon-zoom-in">
-            <component :is="PlusIcon" />
-          </slot>
-        </ControlButton>
+      <slot name="control-zoom-in" :disabled="maxZoomReached" :zoom-in="onZoomInHandler" :icon="PlusIcon">
+        <slot name="control-item" control="zoom-in" :disabled="maxZoomReached" :on-click="onZoomInHandler" :icon="PlusIcon">
+          <ControlButton class="vue-flow__controls-zoomin" :disabled="maxZoomReached" @click="onZoomInHandler">
+            <slot name="icon-zoom-in">
+              <component :is="PlusIcon" />
+            </slot>
+          </ControlButton>
+        </slot>
       </slot>
 
-      <slot name="control-zoom-out">
-        <ControlButton class="vue-flow__controls-zoomout" :disabled="minZoomReached" @click="onZoomOutHandler">
-          <slot name="icon-zoom-out">
-            <component :is="MinusIcon" />
-          </slot>
-        </ControlButton>
+      <slot name="control-zoom-out" :disabled="minZoomReached" :zoom-out="onZoomOutHandler" :icon="MinusIcon">
+        <slot name="control-item" control="zoom-out" :disabled="minZoomReached" :on-click="onZoomOutHandler" :icon="MinusIcon">
+          <ControlButton class="vue-flow__controls-zoomout" :disabled="minZoomReached" @click="onZoomOutHandler">
+            <slot name="icon-zoom-out">
+              <component :is="MinusIcon" />
+            </slot>
+          </ControlButton>
+        </slot>
       </slot>
     </template>
 
     <template v-if="showFitView">
-      <slot name="control-fit-view">
-        <ControlButton class="vue-flow__controls-fitview" @click="onFitViewHandler">
-          <slot name="icon-fit-view">
-            <component :is="FitView" />
-          </slot>
-        </ControlButton>
+      <slot name="control-fit-view" :fit-view="onFitViewHandler" :icon="FitView">
+        <slot name="control-item" control="fit-view" :on-click="onFitViewHandler" :icon="FitView">
+          <ControlButton class="vue-flow__controls-fitview" @click="onFitViewHandler">
+            <slot name="icon-fit-view">
+              <component :is="FitView" />
+            </slot>
+          </ControlButton>
+        </slot>
       </slot>
     </template>
 
     <template v-if="showInteractive">
-      <slot name="control-interactive">
-        <ControlButton v-if="showInteractive" class="vue-flow__controls-interactive" @click="onInteractiveChangeHandler">
-          <slot v-if="isInteractive" name="icon-unlock">
-            <component :is="Unlock" />
-          </slot>
-          <slot v-if="!isInteractive" name="icon-lock">
-            <component :is="Lock" />
-          </slot>
-        </ControlButton>
+      <slot
+        name="control-interactive"
+        :interactive="isInteractive"
+        :toggle-interactive="onInteractiveChangeHandler"
+        :icon="isInteractive ? Unlock : Lock"
+        :lock-icon="Lock"
+        :unlock-icon="Unlock"
+      >
+        <slot
+          name="control-item"
+          control="interactive"
+          :on-click="onInteractiveChangeHandler"
+          :icon="isInteractive ? Unlock : Lock"
+        >
+          <ControlButton v-if="showInteractive" class="vue-flow__controls-interactive" @click="onInteractiveChangeHandler">
+            <slot v-if="isInteractive" name="icon-unlock">
+              <component :is="Unlock" />
+            </slot>
+            <slot v-if="!isInteractive" name="icon-lock">
+              <component :is="Lock" />
+            </slot>
+          </ControlButton>
+        </slot>
       </slot>
     </template>
 
-    <slot />
+    <slot v-bind="slotProps" />
   </Panel>
 </template>
diff --git a/packages/controls/src/svg.d.ts b/packages/controls/src/svg.d.ts
new file mode 100644
index 000000000..d5999c20f
--- /dev/null
+++ b/packages/controls/src/svg.d.ts
@@ -0,0 +1,8 @@
+// We are using vite-svg-loader which imports SVGs as Vue components instead of strings
+// so we need to overwrite the default Vite declaration for SVGs here.
+declare module '*.svg' {
+  import type { Component } from 'vue'
+
+  const component: Component
+  export default component
+}
diff --git a/packages/controls/src/types.ts b/packages/controls/src/types.ts
index 048ca62e3..1c64f77dd 100644
--- a/packages/controls/src/types.ts
+++ b/packages/controls/src/types.ts
@@ -1,3 +1,4 @@
+import type { Component } from 'vue'
 import type { FitViewParams, PanelPosition, PanelPositionType } from '@vue-flow/core'
 
 export interface ControlProps {
@@ -12,3 +13,45 @@ export interface ControlProps {
   /** Position of the controls {@link PanelPosition} */
   position?: PanelPositionType | PanelPosition
 }
+
+export type ControlType = 'zoom-in' | 'zoom-out' | 'fit-view' | 'interactive'
+
+export interface ControlItemSlotProps {
+  /** Type of the control button */
+  control: ControlType
+  /** Whether the button is disabled */
+  disabled?: boolean
+  /** Default click handler */
+  onClick: () => any
+  /** Default icon component reflecting the control type and state */
+  icon: Component
+}
+
+export interface ControlsSlotProps {
+  /** Whether the zoom in button is disabled */
+  zoomInDisabled: boolean
+  /** Zoom in button click handler */
+  zoomIn: () => any
+  /** Zoom in icon component */
+  zoomInIcon: Component
+  /** Whether the zoom out button is disabled */
+  zoomOutDisabled: boolean
+  /** Zoom out button click handler */
+  zoomOut: () => any
+  /** Zoom out icon component */
+  zoomOutIcon: Component
+  /** Fit view button click handler */
+  fitView: () => any
+  /** Fit view icon component */
+  fitViewIcon: Component
+  /** Whether the interaction is enabled */
+  interactive: boolean
+  /** Toggle interaction button */
+  toggleInteractive: () => any
+  /** Interactive icon component reflecting current state */
+  interactiveIcon: Component
+  /** Lock icon component */
+  lockIcon: Component
+  /** Unlock icon component */
+  unlockIcon: Component
+}
diff --git a/packages/controls/tsconfig.json b/packages/controls/tsconfig.json
index f02b0a03e..07f32eee9 100644
--- a/packages/controls/tsconfig.json
+++ b/packages/controls/tsconfig.json
@@ -2,13 +2,8 @@
   "extends": "@tooling/tsconfig/base",
   "compilerOptions": {
     "baseUrl": ".",
-    "declarationDir": "./dist",
-    "types": [
-      "vite/client",
-      "vue/macros"
-    ]
+    "types": ["vite/client", "vue/macros"],
+    "declarationDir": "./dist"
   },
-  "include": [
-    "./src"
-  ]
+  "include": ["./src"]
 }