alighasami/vue-flow
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(guide): update theming page

Browse Source
This commit is contained in:
braks
2023-11-05 18:43:33 +01:00
committed by Braks
parent fcf3078d5b
commit 372c37469e
2 changed files with 186 additions and 99 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/src/guide/getting-started.md
+14 -6
View File
@@ -14,14 +14,22 @@ Before you strap in, make sure you're equipped with:
Use your preferred package manager to install Vue Flow:
```bash
npm i --save @vue-flow/core
::: code-group
yarn add @vue-flow/core
pnpm i @vue-flow/core
```sh [npm]
$ npm add @vue-flow/core
```
```sh [pnpm]
$ pnpm add @vue-flow/core
```
```sh [yarn]
$ yarn add @vue-flow/core
```
:::
## Usage
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
Nodes additionally need an [XY-position](/typedocs/interfaces/XYPosition), while edges require a source and a
target, both represented by node ids.
::: warning Pay Attention!
::: warning NOTE!
To ensure Vue Flow's is correctly displayed, make sure you include the necessary styles.
Refer to the [Theming](/guide/theming) section for additional information.
docs/src/guide/theming.md
+172 -93
View File
@@ -1,8 +1,34 @@
# Theming
<script setup>
import LogosJavascript from '~icons/logos/javascript';
import LogosTypescript from '~icons/logos/typescript-icon';
import { ref, h } from 'vue';
import { Handle, Position, VueFlow } from '@vue-flow/core';
## Library styles
VueFlow comes without any pre-injected stylings. Some necessary stylings have to be imported, though optional styles (i.e.
the default theme) can be skipped.
const CustomNode = (props) => h('div', [
h(Handle, { connectable: false, type: 'target', position: Position.Top }),
h('div', props.label),
h(Handle, { connectable: false, type: 'source', position: Position.Bottom }),
]);
const elements = ref([
{ id: '1', label: 'Node 1', position: { x: 0, y: 0 }, draggable: false, deletable: false, selectable: false, type: 'custom' },
{ id: '2', label: 'Node 2', position: { x: 75, y: 75 }, draggable: false, deletable: false, selectable: false, type: 'custom' },
{ id: 'e1-2', source: '1', target: '2', animated: true, selectable: false, deletable: false },
])
</script>
# Getting Creative with Theming
Let's take a tour around the library styles, customization opportunities, and other features that Vue Flow offers out of
the box.
## Library Styles
Vue Flow values flexibility and allows you to take the lead when it comes to styling.
It showcases some obligatory stylings that must be imported, while leaving optional features, such as the default theme,
up to your preference.
To import the necessary and optional styles:
```css
/* these are necessary styles for vue flow */
@@ -12,37 +38,93 @@ the default theme) can be skipped.
@import '@vue-flow/core/dist/theme-default.css';
```
## Customizing default theme
## Tweaking the Default Theme
When you are using the default theme there are three ways how you can style the graph pane and the elements. You can create
your own CSS rules, pass style/class properties to the components or use the available css variables.
The Vue Flow default theme functions as your baseline, which you can customize and decorate as per your liking using CSS
rules, style and class properties, and CSS variables.
### Using classes
### Styling with CSS Classes
You can customize the default theme by simply overwriting the class definitions with your own custom ones.
Here's how you can use CSS classes to add a pop of color or alter the font style for the theme:
```css
.vue-flow {
background: red;
/* Use a purple theme for our custom node */
.vue-flow__node-custom {
background: purple;
color: white;
border: 1px solid purple;
border-radius: 4px;
box-shadow: 0 0 0 1px purple;
padding: 8px;
}
```
### Using styles
<div class="mt-4 bg-[var(--vp-code-block-bg)] rounded-lg h-50">
<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>
<template #node-custom="props">
<CustomNode v-bind="props" />
</template>
</VueFlow>
</div>
You can also pass a style or class attribute directly to the Vue Flow component.
<style>
.vue-flow__node-custom {
background: purple;
color: white;
border: 1px solid purple;
border-radius: 4px;
box-shadow: 0 0 0 1px purple;
padding: 8px;
}
</style>
s
### Using CSS Properties
```vue{4}
You can also directly pass a style or class attribute to Vue Flow components and nodes/edges.
Below are a couple of examples on how you can do this:
Directly styling the Vue Flow component:
```vue{5-6,8-9}
<div style="height: 300px">
<VueFlow
v-model="elements"
<!-- You can pass a class name to the component -->
class="my-diagram-class"
<!-- You can pass an object containing CSSProperties or CSS variables -->
:style="{ background: 'red' }"
/>
</div>
```
Nodes/Edges can also be styled with a style or class attribute.
Styling nodes/edges with a style or class attribute:
```ts{7-11,19-26}
::: code-group
```js{8-12} [<LogosJavascript />]
/* Customizing node by assigning class and style properties */
const nodes = ref([
{
id: '1',
label: 'Node 1',
position: { x: 250, y: 5 },
// Add a class name to the node
class: 'my-custom-node-class',
// You can pass an object containing CSSProperties or CSS variables
style: { backgroundColor: 'green', width: '200px', height: '100px' },
},
])
```
```ts{10-14} [<LogosTypescript />]
import type { Node } from '@vue-flow/core';
/* Customizing node by assigning class and style properties */
const nodes = ref<Node[]>([
{
id: '1',
@@ -55,98 +137,95 @@ const nodes = ref<Node[]>([
// You can pass an object containing CSSProperties or CSS variables
style: { backgroundColor: 'green', width: '200px', height: '100px' },
},
{
id: '2',
label: 'Node 2',
position: { x: 100, y: 100 },
/*
* You can also use a function which will receive your current element as it's input.
* Useful if you want to add styles if the element is selected
*/
style: (el) => {
if (el.selected) return { background: 'purple' }
return { background: 'green' }
}
},
])
```
### [Using CSS variables](/typedocs/types/CSSVars)
:::
Some theme stylings can be overwritten by using css variables.
These variables can either be applied globally or you can define them on an element basis.
### [Redefining Styles with CSS variables](/typedocs/types/CSSVars)
Some of the defined theme styles can be overwritten using CSS variables.
These alterations can be implemented either on a global scale or to individual elements.
::: code-group
```css
/* global defaults */
/* Global default CSS variable values */
:root {
--vf-node-bg: #fff;
--vf-node-text: #222;
--vf-connection-path: #b1b1b7;
--vf-handle: #555;
--vf-node-bg: #fff;
--vf-node-text: #222;
--vf-connection-path: #b1b1b7;
--vf-handle: #555;
}
```
```ts{4-5}
const elements = ref<Elements>([
{ id: '1', type: 'input', label: 'Node 1', position: { x: 250, y: 5 } },
// Overwrite the `--vf-node-color` variable to change the border, box-shadow and handle color of a node
{ id: '2', label: 'Node 2', position: { x: 100, y: 100 }, style: { '--vf-node-color': 'blue' } },
{ id: '3', label: 'Node 3', position: { x: 400, y: 100 } },
{ id: '4', label: 'Node 4', position: { x: 400, y: 200 } },
{ id: 'e1-2', source: '1', target: '2', animated: true },
{ id: 'e1-3', source: '1', target: '3' },
```js{2-3} [<LogosJavascript />]
const elements = ref([
/* Overriding the `--vf-node-color` variable to change node border, box-shadow and handle color */
{ id: '1', label: 'Node 1', position: { x: 100, y: 100 }, style: { '--vf-node-color': 'blue' } },
])
```
```ts{4-5} [<LogosTypescript />]
import type { Elements } from '@vue-flow/core';
const elements = ref<Elements>([
/* Overriding the `--vf-node-color` variable to change node border, box-shadow and handle color */
{ id: '1', label: 'Node 1', position: { x: 100, y: 100 }, style: { '--vf-node-color': 'blue' } },
])
```
:::
## CSS Variables
| Variable | Effect |
|-----------------------|------------------------------------------|
| --vf-node-color | Node border, box-shadow and handle color |
| --vf-box-shadow | Node box-shadow color |
| --vf-node-bg | Node background color |
| --vf-node-text | Node font color |
| --vf-handle | Node handle color |
| --vf-connection-path | Connectionline color |
Here's a concise list of CSS variables you can consider, along with their effects:
## Classes
| Variable | Effect |
|----------------------|----------------------------------------------------|
| --vf-node-color | Defines node border, box-shadow, and handle colors |
| --vf-box-shadow | Defines color of node box-shadow |
| --vf-node-bg | Defines node background color |
| --vf-node-text | Defines node text color |
| --vf-handle | Defines node handle color |
| --vf-connection-path | Defines connection line color |
| Name | Container |
|-------------------------------|----------------------------------------------------------|
| .vue-flow | Outer container |
| .vue-flow__container | Wrapping container elements |
| .vue-flow__viewport | Inner container |
| .vue-flow__transformationpane | Zoom & pan pane |
| .vue-flow__selectionpane | Selection pane |
| .vue-flow__selection | User selection |
| .vue-flow__edges | Edges renderer wrapper |
| .vue-flow__edge | Edge element wrapper |
| .vue-flow__edge-{type} | Edge type, either a custom or default type |
| .vue-flow__edge .selected | Selected Edge |
| .vue-flow__edge .animated | Animated edge |
| .vue-flow__edge-path | Edge element svg path |
| .vue-flow__edge-text | Edge label wrapper |
| .vue-flow__edge-textbg | Edge label wrapper background |
| .vue-flow__connectionline | Connection line container element |
| .vue-flow__connection | Connection line element |
| .vue-flow__connection-path | Connection line svg path |
| .vue-flow__nodes | Nodes renderer wrapper |
| .vue-flow__node | Node element wrapper |
| .vue-flow__node .selected | Selected Node |
| .vue-flow__node-{type} | Node type, either a custom or default type |
| .vue-flow__nodesselection | Nodes selection rect |
| .vue-flow__handle | Node handle element wrapper |
| .vue-flow__handle-bottom | Handle position bottom |
| .vue-flow__handle-top | Handle position top |
| .vue-flow__handle-left | Handle position left |
| .vue-flow__handle-right | Handle position right |
| .vue-flow__handle-connecting | Connectionline is above handle |
| .vue-flow__handle-valid | Connectionline is above handle & the connection is valid |
| .vue-flow__background | Background component |
| .vue-flow__minimap | Mini map component |
| .vue-flow__controls | Controls component |
## CSS Class Names
Here you'll find a handy reference guide of class names and their respective containers:
| Name | Container |
|-------------------------------|---------------------------------------------------|
| .vue-flow | The outer container |
| .vue-flow__container | Wrapper for container elements |
| .vue-flow__viewport | The inner container |
| .vue-flow__transformationpane | Pane for movements like zooming and panning |
| .vue-flow__selectionpane | Pane for handling user selection |
| .vue-flow__selection | Defines current user selection box |
| .vue-flow__edges | Wrapper rendering edges |
| .vue-flow__edge | Wrapper around each edge element |
| .vue-flow__edge-{type} | Edge type (either custom or default) |
| .vue-flow__edge .selected | Defines the currently selected edge(s) |
| .vue-flow__edge .animated | Defines an animated edge |
| .vue-flow__edge-path | SVG path for edge elements |
| .vue-flow__edge-text | Wrapper around edge label |
| .vue-flow__edge-textbg | Background wrapper around edge label |
| .vue-flow__connectionline | Container for the connection line elements |
| .vue-flow__connection | Individual connection line element |
| .vue-flow__connection-path | SVG path for connection line |
| .vue-flow__nodes | Rendering wrapper around nodes |
| .vue-flow__node | Wrapper around each node element |
| .vue-flow__node .selected | Defines the currently selected node(s) |
| .vue-flow__node-{type} | Node type (either custom or default) |
| .vue-flow__nodesselection | Defines selection rectangle for nodes |
| .vue-flow__handle | Wrapper around node handle elements |
| .vue-flow__handle-bottom | Defines a handle at bottom |
| .vue-flow__handle-top | Defines a handle at top |
| .vue-flow__handle-left | Defines a handle at left |
| .vue-flow__handle-right | Defines a handle at right |
| .vue-flow__handle-connecting | Connection line is over the handle |
| .vue-flow__handle-valid | Connection line over handle with valid connection |
| .vue-flow__background | Background component |
| .vue-flow__minimap | MiniMap component |
| .vue-flow__controls | Controls component |