From 372c37469ebfc88cdd9ab0e0fd8a1407c6f24486 Mon Sep 17 00:00:00 2001
From: braks <78412429+bcakmakoglu@users.noreply.github.com>
Date: Sun, 5 Nov 2023 13:33:06 +0100
Subject: [PATCH] docs(guide): update theming page
---
docs/src/guide/getting-started.md | 20 ++-
docs/src/guide/theming.md | 265 +++++++++++++++++++-----------
2 files changed, 186 insertions(+), 99 deletions(-)
diff --git a/docs/src/guide/getting-started.md b/docs/src/guide/getting-started.md
index c9e3c552..d9e28442 100644
--- a/docs/src/guide/getting-started.md
+++ b/docs/src/guide/getting-started.md
@@ -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 [edges](/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.
diff --git a/docs/src/guide/theming.md b/docs/src/guide/theming.md
index 8d1df006..434b9854 100644
--- a/docs/src/guide/theming.md
+++ b/docs/src/guide/theming.md
@@ -1,8 +1,34 @@
-# Theming
+
+
+# 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
+
+
+
+
+
+
+
-You can also pass a style or class attribute directly to the Vue Flow component.
+
+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}
+ class="my-diagram-class"
+
+
:style="{ background: 'red' }"
/>
```
-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} []
+/* 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} []
+import type { Node } from '@vue-flow/core';
+
+/* Customizing node by assigning class and style properties */
const nodes = ref([
{
id: '1',
@@ -55,98 +137,95 @@ const nodes = ref([
// 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([
- { 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} []
+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} []
+import type { Elements } from '@vue-flow/core';
+
+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' } },
+])
+```
+
+:::
+
## 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 |