Skip to content

Commit 50d7d41

Browse files
silentoplayzsilentoplayz
committed
doc: Theming system page
This commit adds a new tutorial that explains how to customize and add new themes to Open WebUI.
1 parent ca9ab27 commit 50d7d41

File tree

1 file changed

+169
-0
lines changed

1 file changed

+169
-0
lines changed

‎docs/tutorials/theming.mdx‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
---
2+
sidebar_position: 99
3+
title: "🎨 Theming"
4+
---
5+
6+
# ✨ Theming
7+
8+
Open WebUI features a robust theming system that allows you to customize the application's appearance to your liking. Whether you're a user who wants to personalize your experience or a developer looking to create and share your own themes, this guide has you covered.
9+
10+
## For Users: Managing Themes
11+
12+
### Built-in Themes
13+
14+
Open WebUI comes with several pre-installed themes:
15+
16+
- **System**: Automatically syncs with your operating system's light or dark mode.
17+
- **Light**: A clean and bright interface.
18+
- **Dark**: A classic dark mode.
19+
- **OLED Dark**: An even darker mode designed for OLED screens, with true black backgrounds.
20+
- **Her**: A special theme inspired by the movie "Her".
21+
22+
You can switch between these themes at any time in the `Settings > Themes` menu.
23+
24+
### Community Themes
25+
26+
The real power of the theming system lies in "Community Themes." These are themes created and shared by other users, allowing for a vast range of visual styles.
27+
28+
#### Installing Community Themes
29+
30+
You can install community themes in two main ways:
31+
32+
1. **From a URL:** If a developer provides a URL to a `theme.json` file, you can add it directly:
33+
* Go to `Settings > Themes`.
34+
* Under "Import Community Theme," paste the URL into the input field and click **Add**.
35+
36+
2. **From a File:** If you've downloaded a `theme.json` file:
37+
* Go to `Settings > Themes`.
38+
* Click on **Import File** and select the `theme.json` file from your computer.
39+
40+
#### Managing Installed Themes
41+
42+
Once installed, community themes appear in the theme list alongside the built-in ones. You can:
43+
44+
- **Select Theme:** Click on a theme in the list to apply it immediately.
45+
- **Live Preview in Editor:** When creating a new theme or editing an existing one, the Theme Editor provides a real-time preview of your changes.
46+
- **Update:** If a theme developer has provided an update source, Open WebUI will notify you when a new version is available.
47+
- **Edit:** Click the pencil icon to open the Theme Editor and make your own tweaks.
48+
- **Export/Copy:** Share your modified theme by exporting it as a file or copying the JSON to your clipboard.
49+
- **Remove:** Click the trash can icon to delete a community theme.
50+
51+
---
52+
53+
## For Developers: Creating Themes
54+
55+
Creating your own theme is a straightforward process of defining a `Theme` object in a JSON format. You can start from scratch or by editing an existing theme.
56+
57+
### The Theme Object
58+
59+
A theme is a single JSON object with the following properties. Only `id`, `name`, and `base` are strictly required.
60+
61+
| Property | Type | Description |
62+
| -------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
63+
| `id` | `string` | A unique, machine-readable identifier (e.g., `"my-cool-theme"`). **Required**. |
64+
| `name` | `string` | A user-friendly name (e.g., `"My Cool Theme"`). **Required**. |
65+
| `base` | `'light' \| 'dark' \| 'oled-dark' \| 'her'` | The built-in theme to use as a foundation. **Required**. |
66+
| `version` | `string` | The version of your theme (e.g., `"1.0.0"`). Used for updates. |
67+
| `author` | `string` | Your name or username. |
68+
| `repository` | `string` | A URL to the theme's repository, like a GitHub page. |
69+
| `targetWebUIVersion` | `string` | The version of Open WebUI your theme is designed for. |
70+
| `emoji` | `string` | An emoji to represent your theme in the UI. |
71+
| `metaThemeColor` | `string` | A hex color (`#RRGGBB`) for the browser's UI elements. |
72+
| `variables` | `object` | An object where keys are CSS variable names and values are the new colors. |
73+
| `gradient` | `object` | Defines a background gradient. See details below. |
74+
| `tsparticlesConfig` | `object` | A configuration object for [tsParticles](https://particles.js.org/). |
75+
| `animationScript` | `string` | A string of JavaScript code to be run in a web worker for custom canvas animations. |
76+
| `css` | `string` | A string of custom CSS rules to be injected. |
77+
| `sourceUrl` | `string` | A URL pointing to the raw `theme.json` file, allowing for automatic update checks. |
78+
| `codeMirrorTheme` | `string` | The name of a [CodeMirror theme](https://codemirror.net/5/demo/theme.html) for the text editor. |
79+
80+
### Creating a Theme
81+
82+
The easiest way to start is using the built-in Theme Editor:
83+
84+
1. Navigate to `Settings > Themes`.
85+
2. Click the **Add Manually** button. This opens the Theme Editor with a basic template.
86+
3. Modify the properties. The editor provides a live preview as you make changes.
87+
4. Once you're happy, click **Save**.
88+
89+
### Example 1: Simple Color Theme
90+
91+
This theme creates a "Forest" look by overriding the default CSS color variables.
92+
93+
```json
94+
{
95+
"id": "forest",
96+
"name": "Forest",
97+
"base": "dark",
98+
"author": "Jules",
99+
"emoji": "🌲",
100+
"metaThemeColor": "#1A3622",
101+
"variables": {
102+
"--color-gray-950": "#0D1A13",
103+
"--color-gray-900": "#1A3622",
104+
"--color-gray-850": "#22482D",
105+
"--color-primary": "#6B8E23"
106+
}
107+
}
108+
```
109+
110+
### Example 2: Gradient Background Theme
111+
112+
This theme adds a subtle, animated gradient to the background.
113+
114+
```json
115+
{
116+
"id": "ocean-breeze",
117+
"name": "Ocean Breeze",
118+
"base": "light",
119+
"emoji": "🌊",
120+
"gradient": {
121+
"enabled": true,
122+
"colors": ["#a8c0ff", "#3f2b96"],
123+
"direction": 120,
124+
"intensity": 80
125+
}
126+
}
127+
```
128+
129+
### Example 3: tsParticles Theme
130+
131+
This theme uses `tsParticles` to create an interactive particle background. Paste a valid `tsParticles` JSON config into the `tsparticlesConfig` property.
132+
133+
```json
134+
{
135+
"id": "starfield",
136+
"name": "Starfield",
137+
"base": "oled-dark",
138+
"emoji": "✨",
139+
"tsparticlesConfig": {
140+
"particles": {
141+
"number": { "value": 160, "density": { "enable": true, "value_area": 800 } },
142+
"color": { "value": "#ffffff" },
143+
"shape": { "type": "circle" },
144+
"opacity": { "value": 1, "random": true },
145+
"size": { "value": 3, "random": true },
146+
"line_linked": { "enable": false },
147+
"move": { "enable": true, "speed": 1, "direction": "none", "random": true, "straight": false, "out_mode": "out" }
148+
}
149+
}
150+
}
151+
```
152+
153+
### Example 4: Custom Animation Theme
154+
155+
For complete control, you can provide JavaScript for a custom canvas animation. This script runs in a separate worker thread for performance.
156+
157+
```json
158+
{
159+
"id": "matrix-rain",
160+
"name": "Matrix Rain",
161+
"base": "oled-dark",
162+
"emoji": "🔢",
163+
"animationScript": "const canvas = self.canvas; const ctx = canvas.getContext('2d'); let columns; let drops; function setup() { const width = self.width; const height = self.height; canvas.width = width; canvas.height = height; columns = Math.floor(width / 20); drops = []; for (let i = 0; i < columns; i++) { drops[i] = 1; } } function draw() { ctx.fillStyle = 'rgba(0, 0, 0, 0.05)'; ctx.fillRect(0, 0, canvas.width, canvas.height); ctx.fillStyle = '#0F0'; ctx.font = '15px monospace'; for (let i = 0; i < drops.length; i++) { const text = String.fromCharCode(0x30A0 + Math.random() * 96); ctx.fillText(text, i * 20, drops[i] * 20); if (drops[i] * 20 > canvas.height && Math.random() > 0.975) { drops[i] = 0; } drops[i]++; } } self.onmessage = (e) => { if (e.data.type === 'init') { self.canvas = e.data.canvas; setup(); setInterval(draw, 33); } else if (e.data.type === 'resize') { self.width = e.data.width; self.height = e.data.height; setup(); } };"
164+
}
165+
```
166+
167+
### Sharing Your Theme
168+
169+
To make your theme easily shareable and updatable, host the `theme.json` file somewhere with a raw file link (like GitHub Gist or a public repository) and set the `sourceUrl` property to that link. This allows others to install your theme with one click and receive updates automatically.

0 commit comments

Comments
 (0)