Skip to content

Commit 372c374

Browse files
bcakmakoglubcakmakoglu
committed
docs(guide): update theming page
1 parent fcf3078 commit 372c374

File tree

2 files changed

+184
-97
lines changed

2 files changed

+184
-97
lines changed

‎docs/src/guide/getting-started.md

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -14,14 +14,22 @@ Before you strap in, make sure you're equipped with:
1414

1515
Use your preferred package manager to install Vue Flow:
1616

17-
```bash
18-
npm i --save @vue-flow/core
17+
::: code-group
1918

20-
yarn add @vue-flow/core
19+
```sh [npm]
20+
$ npm add @vue-flow/core
21+
```
22+
23+
```sh [pnpm]
24+
$ pnpm add @vue-flow/core
25+
```
2126

22-
pnpm i @vue-flow/core
27+
```sh [yarn]
28+
$ yarn add @vue-flow/core
2329
```
2430

31+
:::
32+
2533
## Usage
2634

2735
In Vue Flow, an application structure consists
@@ -34,7 +42,7 @@ and [<span class="font-bold">edges</span>](/typedocs/types/Edge), all of which a
3442
Nodes additionally need an [XY-position](/typedocs/interfaces/XYPosition), while edges require a source and a
3543
target, both represented by node ids.
3644

37-
::: warning Pay Attention!
45+
::: warning NOTE!
3846
To ensure Vue Flow's is correctly displayed, make sure you include the necessary styles.
3947

4048
Refer to the [Theming](/guide/theming) section for additional information.

‎docs/src/guide/theming.md

Lines changed: 171 additions & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,34 @@
1-
# Theming
1+
<script setup>
2+
import LogosJavascript from '~icons/logos/javascript';
3+
import LogosTypescript from '~icons/logos/typescript-icon';
4+
import { ref, h } from 'vue';
5+
import { Handle, Position, VueFlow } from '@vue-flow/core';
6+
7+
const CustomNode = (props) => h('div', [
8+
h(Handle, { connectable: false, type: 'target', position: Position.Top }),
9+
h('div', props.label),
10+
h(Handle, { connectable: false, type: 'source', position: Position.Bottom }),
11+
]);
12+
13+
const elements = ref([
14+
{ id: '1', label: 'Node 1', position: { x: 0, y: 0 }, draggable: false, deletable: false, selectable: false, type: 'custom' },
15+
{ id: '2', label: 'Node 2', position: { x: 75, y: 75 }, draggable: false, deletable: false, selectable: false, type: 'custom' },
16+
{ id: 'e1-2', source: '1', target: '2', animated: true, selectable: false, deletable: false },
17+
])
18+
</script>
19+
20+
# Getting Creative with Theming
21+
22+
Let's take a tour around the library styles, customization opportunities, and other features that Vue Flow offers out of
23+
the box.
24+
25+
## Library Styles
26+
27+
Vue Flow values flexibility and allows you to take the lead when it comes to styling.
28+
It showcases some obligatory stylings that must be imported, while leaving optional features, such as the default theme,
29+
up to your preference.
230

3-
## Library styles
4-
VueFlow comes without any pre-injected stylings. Some necessary stylings have to be imported, though optional styles (i.e.
5-
the default theme) can be skipped.
31+
To import the necessary and optional styles:
632

733
```css
834
/* these are necessary styles for vue flow */
@@ -12,38 +38,75 @@ the default theme) can be skipped.
1238
@import '@vue-flow/core/dist/theme-default.css';
1339
```
1440

15-
## Customizing default theme
41+
## Tweaking the Default Theme
1642

17-
When you are using the default theme there are three ways how you can style the graph pane and the elements. You can create
18-
your own CSS rules, pass style/class properties to the components or use the available css variables.
43+
The Vue Flow default theme functions as your baseline, which you can customize and decorate as per your liking using CSS
44+
rules, style and class properties, and CSS variables.
1945

20-
### Using classes
46+
### Styling with CSS Classes
2147

22-
You can customize the default theme by simply overwriting the class definitions with your own custom ones.
48+
Here's how you can use CSS classes to add a pop of color or alter the font style for the theme:
2349

2450
```css
25-
.vue-flow {
26-
background: red;
51+
/* Use a purple theme for our custom node */
52+
.vue-flow__node-custom {
53+
background: purple;
54+
color: white;
55+
border: 1px solid purple;
56+
border-radius: 4px;
57+
box-shadow: 0 0 0 1px purple;
58+
padding: 8px;
2759
}
2860
```
2961

30-
### Using styles
62+
<div class="mt-4 bg-[var(--vp-code-block-bg)] rounded-lg h-50">
63+
<VueFlow v-model="elements" :pan-activation-key-code="null" :pan-on-scroll="false" :zoom-on-scroll="false" :pan-on-drag="false" fit-view-on-init>
64+
<template #node-custom="props">
65+
<CustomNode v-bind="props" />
66+
</template>
67+
</VueFlow>
68+
</div>
69+
70+
<style>
71+
.vue-flow__node-custom {
72+
background: purple;
73+
color: white;
74+
border: 1px solid purple;
75+
border-radius: 4px;
76+
box-shadow: 0 0 0 1px purple;
77+
padding: 8px;
78+
}
79+
</style>
80+
s
81+
### Using CSS Properties
82+
83+
You can also directly pass a style or class attribute to Vue Flow components and nodes/edges.
3184

32-
You can also pass a style or class attribute directly to the Vue Flow component.
85+
Below are a couple of examples on how you can do this:
3386

34-
```vue{4}
87+
Directly styling the Vue Flow component:
88+
89+
```vue{5-6,8-9}
3590
<div style="height: 300px">
3691
<VueFlow
3792
v-model="elements"
93+
94+
<!-- You can pass a class name to the component -->
95+
class="my-diagram-class"
96+
97+
<!-- You can pass an object containing CSSProperties or CSS variables -->
3898
:style="{ background: 'red' }"
3999
/>
40100
</div>
41101
```
42102

43-
Nodes/Edges can also be styled with a style or class attribute.
103+
Styling nodes/edges with a style or class attribute:
44104

45-
```ts{7-11,19-26}
46-
const nodes = ref<Node[]>([
105+
::: code-group
106+
107+
```js{8-12} [<LogosJavascript />]
108+
/* Customizing node by assigning class and style properties */
109+
const nodes = ref([
47110
{
48111
id: '1',
49112
label: 'Node 1',
@@ -55,98 +118,114 @@ const nodes = ref<Node[]>([
55118
// You can pass an object containing CSSProperties or CSS variables
56119
style: { backgroundColor: 'green', width: '200px', height: '100px' },
57120
},
58-
121+
])
122+
```
123+
124+
```ts{10-14} [<LogosTypescript />]
125+
import type { Node } from '@vue-flow/core';
126+
127+
/* Customizing node by assigning class and style properties */
128+
const nodes = ref<Node[]>([
59129
{
60-
id: '2',
61-
label: 'Node 2',
62-
position: { x: 100, y: 100 },
130+
id: '1',
131+
label: 'Node 1',
132+
position: { x: 250, y: 5 },
63133
64-
/*
65-
* You can also use a function which will receive your current element as it's input.
66-
* Useful if you want to add styles if the element is selected
67-
*/
68-
style: (el) => {
69-
if (el.selected) return { background: 'purple' }
70-
return { background: 'green' }
71-
}
134+
// Add a class name to the node
135+
class: 'my-custom-node-class',
136+
137+
// You can pass an object containing CSSProperties or CSS variables
138+
style: { backgroundColor: 'green', width: '200px', height: '100px' },
72139
},
73140
])
74141
```
75142

76-
### [Using CSS variables](/typedocs/types/CSSVars)
143+
:::
144+
145+
### [Redefining Styles with CSS variables](/typedocs/types/CSSVars)
77146

78-
Some theme stylings can be overwritten by using css variables.
79-
These variables can either be applied globally or you can define them on an element basis.
147+
Some of the defined theme styles can be overwritten using CSS variables.
148+
These alterations can be implemented either on a global scale or to individual elements.
149+
150+
::: code-group
80151

81152
```css
82-
/* global defaults */
153+
/* Global default CSS variable values */
83154
:root {
84-
--vf-node-bg: #fff;
85-
--vf-node-text: #222;
86-
--vf-connection-path: #b1b1b7;
87-
--vf-handle: #555;
155+
--vf-node-bg: #fff;
156+
--vf-node-text: #222;
157+
--vf-connection-path: #b1b1b7;
158+
--vf-handle: #555;
88159
}
89160
```
90161

91-
```ts{4-5}
162+
```js{2-3} [<LogosJavascript />]
163+
const elements = ref([
164+
/* Overriding the `--vf-node-color` variable to change node border, box-shadow and handle color */
165+
{ id: '1', label: 'Node 1', position: { x: 100, y: 100 }, style: { '--vf-node-color': 'blue' } },
166+
])
167+
```
168+
169+
```ts{4-5} [<LogosTypescript />]
170+
import type { Elements } from '@vue-flow/core';
171+
92172
const elements = ref<Elements>([
93-
{ id: '1', type: 'input', label: 'Node 1', position: { x: 250, y: 5 } },
94-
95-
// Overwrite the `--vf-node-color` variable to change the border, box-shadow and handle color of a node
96-
{ id: '2', label: 'Node 2', position: { x: 100, y: 100 }, style: { '--vf-node-color': 'blue' } },
97-
98-
{ id: '3', label: 'Node 3', position: { x: 400, y: 100 } },
99-
{ id: '4', label: 'Node 4', position: { x: 400, y: 200 } },
100-
{ id: 'e1-2', source: '1', target: '2', animated: true },
101-
{ id: 'e1-3', source: '1', target: '3' },
173+
/* Overriding the `--vf-node-color` variable to change node border, box-shadow and handle color */
174+
{ id: '1', label: 'Node 1', position: { x: 100, y: 100 }, style: { '--vf-node-color': 'blue' } },
102175
])
103176
```
104177

178+
:::
179+
105180
## CSS Variables
106181

107-
| Variable | Effect |
108-
|-----------------------|------------------------------------------|
109-
| --vf-node-color | Node border, box-shadow and handle color |
110-
| --vf-box-shadow | Node box-shadow color |
111-
| --vf-node-bg | Node background color |
112-
| --vf-node-text | Node font color |
113-
| --vf-handle | Node handle color |
114-
| --vf-connection-path | Connectionline color |
115-
116-
## Classes
117-
118-
| Name | Container |
119-
|-------------------------------|----------------------------------------------------------|
120-
| .vue-flow | Outer container |
121-
| .vue-flow__container | Wrapping container elements |
122-
| .vue-flow__viewport | Inner container |
123-
| .vue-flow__transformationpane | Zoom & pan pane |
124-
| .vue-flow__selectionpane | Selection pane |
125-
| .vue-flow__selection | User selection |
126-
| .vue-flow__edges | Edges renderer wrapper |
127-
| .vue-flow__edge | Edge element wrapper |
128-
| .vue-flow__edge-{type} | Edge type, either a custom or default type |
129-
| .vue-flow__edge .selected | Selected Edge |
130-
| .vue-flow__edge .animated | Animated edge |
131-
| .vue-flow__edge-path | Edge element svg path |
132-
| .vue-flow__edge-text | Edge label wrapper |
133-
| .vue-flow__edge-textbg | Edge label wrapper background |
134-
| .vue-flow__connectionline | Connection line container element |
135-
| .vue-flow__connection | Connection line element |
136-
| .vue-flow__connection-path | Connection line svg path |
137-
| .vue-flow__nodes | Nodes renderer wrapper |
138-
| .vue-flow__node | Node element wrapper |
139-
| .vue-flow__node .selected | Selected Node |
140-
| .vue-flow__node-{type} | Node type, either a custom or default type |
141-
| .vue-flow__nodesselection | Nodes selection rect |
142-
| .vue-flow__handle | Node handle element wrapper |
143-
| .vue-flow__handle-bottom | Handle position bottom |
144-
| .vue-flow__handle-top | Handle position top |
145-
| .vue-flow__handle-left | Handle position left |
146-
| .vue-flow__handle-right | Handle position right |
147-
| .vue-flow__handle-connecting | Connectionline is above handle |
148-
| .vue-flow__handle-valid | Connectionline is above handle & the connection is valid |
149-
| .vue-flow__background | Background component |
150-
| .vue-flow__minimap | Mini map component |
151-
| .vue-flow__controls | Controls component |
182+
Here's a concise list of CSS variables you can consider, along with their effects:
183+
184+
| Variable | Effect |
185+
|----------------------|----------------------------------------------------|
186+
| --vf-node-color | Defines node border, box-shadow, and handle colors |
187+
| --vf-box-shadow | Defines color of node box-shadow |
188+
| --vf-node-bg | Defines node background color |
189+
| --vf-node-text | Defines node text color |
190+
| --vf-handle | Defines node handle color |
191+
| --vf-connection-path | Defines connection line color |
192+
193+
## CSS Class Names
194+
195+
Here you'll find a handy reference guide of class names and their respective containers:
196+
197+
| Name | Container |
198+
|-------------------------------|---------------------------------------------------|
199+
| .vue-flow | The outer container |
200+
| .vue-flow__container | Wrapper for container elements |
201+
| .vue-flow__viewport | The inner container |
202+
| .vue-flow__transformationpane | Pane for movements like zooming and panning |
203+
| .vue-flow__selectionpane | Pane for handling user selection |
204+
| .vue-flow__selection | Defines current user selection box |
205+
| .vue-flow__edges | Wrapper rendering edges |
206+
| .vue-flow__edge | Wrapper around each edge element |
207+
| .vue-flow__edge-{type} | Edge type (either custom or default) |
208+
| .vue-flow__edge .selected | Defines the currently selected edge(s) |
209+
| .vue-flow__edge .animated | Defines an animated edge |
210+
| .vue-flow__edge-path | SVG path for edge elements |
211+
| .vue-flow__edge-text | Wrapper around edge label |
212+
| .vue-flow__edge-textbg | Background wrapper around edge label |
213+
| .vue-flow__connectionline | Container for the connection line elements |
214+
| .vue-flow__connection | Individual connection line element |
215+
| .vue-flow__connection-path | SVG path for connection line |
216+
| .vue-flow__nodes | Rendering wrapper around nodes |
217+
| .vue-flow__node | Wrapper around each node element |
218+
| .vue-flow__node .selected | Defines the currently selected node(s) |
219+
| .vue-flow__node-{type} | Node type (either custom or default) |
220+
| .vue-flow__nodesselection | Defines selection rectangle for nodes |
221+
| .vue-flow__handle | Wrapper around node handle elements |
222+
| .vue-flow__handle-bottom | Defines a handle at bottom |
223+
| .vue-flow__handle-top | Defines a handle at top |
224+
| .vue-flow__handle-left | Defines a handle at left |
225+
| .vue-flow__handle-right | Defines a handle at right |
226+
| .vue-flow__handle-connecting | Connection line is over the handle |
227+
| .vue-flow__handle-valid | Connection line over handle with valid connection |
228+
| .vue-flow__background | Background component |
229+
| .vue-flow__minimap | MiniMap component |
230+
| .vue-flow__controls | Controls component |
152231

0 commit comments

Comments
 (0)