Skip to content

Commit 532d522

Browse files
bcakmakoglubcakmakoglu
committed
docs: update handle docs
1 parent c30222e commit 532d522

File tree

2 files changed

+117
-52
lines changed

2 files changed

+117
-52
lines changed

‎docs/src/guide/handle.md

Lines changed: 117 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -8,18 +8,67 @@ Handles are the small circles that are usually placed on the borders of a node.
88
together by dragging a connection-line from one handle to another, resulting in a connection ([Edge](/guide/edge))
99
between the nodes.
1010

11-
Handles are a crucial part of the VueFlow library, as they are the main interaction point for the user to create
12-
connections between nodes.
11+
Handles are a crucial part of VueFlow, as they are the main interaction point for a user to create edges between nodes.
1312

14-
Without handles, it is basically impossible to create edges between nodes, as the `<Handle>` components are used
15-
to calculate the points for the edges.
13+
Without handles, it is basically impossible to create edges between nodes, as the handles are used
14+
to calculate the source and target points for edges.
1615

17-
## Handle Component
16+
## `<Handle>` Component
1817

19-
The `<Handle>` component is a simple component that is used to create a handle for a node. It is a wrapper around a
20-
`<div>` element that provides the necessary event handlers to create edges between nodes.
18+
The `<Handle>` component is a component exported by `@vue-flow/core` that you can use to create a handle for a node.
19+
It is a wrapper around a `<div>` element that provides the necessary event handler bindings to start connections.
2120

22-
The `<Handle>` component is used in the `<Node>` component to create handles for the node.
21+
The `<Handle>` component can be used in a (custom) node component to create handles for the node.
22+
Using `<Handle>` components outside a node component context will not work as expected, so try to avoid this.
23+
24+
```vue
25+
<script setup>
26+
import { Handle } from '@vue-flow/core'
27+
28+
defineProps(['id', 'sourcePosition', 'targetPosition', 'data'])
29+
</script>
30+
31+
<template>
32+
<Handle type="source" :position="sourcePosition" />
33+
34+
<span>{{ data.label }}</span>
35+
36+
<Handle type="target" :position="targetPosition" />
37+
</template>
38+
```
39+
40+
## Handle Positions
41+
42+
Handles can be placed on the following positions:
43+
44+
- `Top`
45+
- `Right`
46+
- `Bottom`
47+
- `Left`
48+
49+
Each position corresponds to a side of the node.
50+
The position of the handle also determines which direction an edge will bend towards when drawn from and to a handle.
51+
52+
For example a handle with `position="Position.Top"` will result in an edge that bends to the *top* when drawn *from* that handle.
53+
A handle with `position="Position.Right"` will result in an edge that bends to the *left* when drawn *to* that handle.
54+
55+
### Adjusting Handle Positions
56+
57+
Handles are positioned on their respective side using CSS with an `absolute` position.
58+
That means you can adjust what element a handle aligns itself with by wrapping it in a container that has a `relative` position.
59+
60+
```vue
61+
<div>
62+
<span>{{ data.label }}</span>
63+
64+
<div style="position: relative; padding: 10px">
65+
<Handle type="source" :position="Position.Right" />
66+
67+
68+
<Handle type="target" :position="Position.Left" />
69+
</div>
70+
</div>
71+
```
2372

2473
## Multiple Handles
2574

@@ -28,8 +77,12 @@ When using multiple handles of the same type (`source` or `target`), each handle
2877

2978
```vue
3079
<!-- each of these handles needs a unique id since we're using two `source` type handles -->
31-
<Handle id="a" type="source" :position="Position.Right" />
32-
<Handle id="b" type="source" :position="Position.Right" />
80+
<Handle id="source-a" type="source" :position="Position.Right" />
81+
<Handle id="source-b" type="source" :position="Position.Right" />
82+
83+
<!-- each of these handles needs a unique id since we're using two `target` type handles -->
84+
<Handle id="target-a" type="target" :position="Position.Left" />
85+
<Handle id="target-b" type="target" :position="Position.Left" />
3386
```
3487

3588
The `id` prop is used to identify the handle when creating edges between nodes. If no `id` is provided, the first handle
@@ -48,7 +101,19 @@ onConnect(({ source, target, sourceHandle, targetHandle }) => {
48101
})
49102
```
50103

51-
## Hide Handles
104+
### Positioning with Multiple Handles
105+
106+
Sometimes you want to add multiple handles to the same side. In that case you often end up having two handles on top of each other instead of next to each other.
107+
Handles will not layout themselves automatically, so you need to manually adjust their position.
108+
109+
You can do so using CSS styles.
110+
For example, you can set the `top` and `bottom` properties to position the handles on the top and bottom of the right side of the node.
111+
```vue
112+
<Handle id="source-a" type="source" :position="Position.Right" style="top: 10px" />
113+
<Handle id="source-b" type="source" :position="Position.Right" style="bottom: 10px; top: auto;" />
114+
```
115+
116+
## Hidden Handles
52117

53118
In some cases you might not want to display a handle at all. You can hide a handle by setting `opacity: 0` as the styles for that handle.
54119

@@ -57,3 +122,44 @@ You cannot hide a handle by removing it from the DOM (for example using `v-if` o
57122
```vue
58123
<Handle type="source" :position="Position.Right" style="opacity: 0" />
59124
```
125+
126+
## Dynamic Handle Positions & Adding/Removing Handles Dynamically
127+
128+
::: tip
129+
In Vue Flow 1.x, there's no need to manually invoke `updateNodeInternals` when dynamically adding handles.
130+
Upon mounting, handles will automatically attempt to attach to the node.
131+
However, if for any reason this isn't happening as expected, you can stick to the guideline provided below to enforce Vue Flow to update the node internals.
132+
:::
133+
134+
At times, you may need to modify handle positions dynamically or programmatically add new handles to a node. In this scenario, the [`updateNodeInternals`](/typedocs/types/UpdateNodeInternals) method found in Vue Flow's API comes in handy.
135+
136+
Invoking this method is vital when dealing with dynamic handles. If not, the node might fail to recognize these new handles, resulting in misaligned edges.
137+
138+
The `updateNodeInternals` function can be deployed in one of two ways:
139+
140+
- **Using the store action:** This approach allows you to update several nodes at once by passing their IDs into the method.
141+
- **Emitting the `updateNodeInternals` event from your customized node component:** This doesn't require any parameters to be passed.
142+
143+
::: code-group
144+
145+
```js [store action]
146+
import { useVueFlow } from '@vue-flow/core'
147+
148+
const { updateNodeInternals } = useVueFlow()
149+
150+
const onSomeEvent = () => {
151+
updateNodeInternals(['1'])
152+
}
153+
```
154+
155+
```vue [emit event]
156+
<script setup>
157+
const emits = defineEmits(['updateNodeInternals'])
158+
159+
const onSomeEvent = () => {
160+
emits('updateNodeInternals')
161+
}
162+
</script>
163+
```
164+
165+
:::

‎docs/src/guide/node.md

Lines changed: 0 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -946,44 +946,3 @@ const inputValue = ref('')
946946
@apply bg-primary rounded p-4;
947947
}
948948
</style>
949-
950-
## Working with Dynamic Handle Positions / Adding Handles Dynamically
951-
952-
::: tip
953-
In Vue Flow 1.x, there's no need to manually invoke `updateNodeInternals` when dynamically adding handles.
954-
Upon mounting, handles will automatically attempt to attach to the node.
955-
However, if for any reason this isn't happening as expected, you can stick to the guideline provided below to enforce Vue Flow to update the node internals.
956-
:::
957-
958-
At times, you may need to modify handle positions dynamically or programmatically add new handles to a node. In this scenario, the [`updateNodeInternals`](/typedocs/types/UpdateNodeInternals) method found in Vue Flow's API comes in handy.
959-
960-
Invoking this method is vital when dealing with dynamic handles. If not, the node might fail to recognize these new handles, resulting in misaligned edges.
961-
962-
The `updateNodeInternals` function can be deployed in one of two ways:
963-
964-
- **Using the store action:** This approach allows you to update several nodes at once by passing their IDs into the method.
965-
- **Emitting the `updateNodeInternals` event from your customized node component:** This doesn't require any parameters to be passed.
966-
967-
::: code-group
968-
969-
```js [store action]
970-
import { useVueFlow } from '@vue-flow/core'
971-
972-
const { updateNodeInternals } = useVueFlow()
973-
974-
const onSomeEvent = () => {
975-
updateNodeInternals(['1'])
976-
}
977-
```
978-
979-
```vue [emit event]
980-
<script setup>
981-
const emits = defineEmits(['updateNodeInternals'])
982-
983-
const onSomeEvent = () => {
984-
emits('updateNodeInternals')
985-
}
986-
</script>
987-
```
988-
989-
:::

0 commit comments

Comments
 (0)