Before submitting, make sure you've checked the following:
Target branch: Please verify that the pull request targets the dev branch.
Description: Provide a concise description of the changes made in this pull request.
Changelog: Ensure a changelog entry following the format of Keep a Changelog is added at the bottom of the PR description.
Documentation: Have you updated relevant documentation Open WebUI Docs, or other documentation sources?
Dependencies: Are there any new dependencies? Have you updated the dependency versions in the documentation?
Testing: Have you written and run sufficient tests to validate the changes?
Code review: Have you performed a self-review of your code, addressing any coding standard issues and ensuring adherence to the project's coding standards?
Prefix: To clearly categorize this pull request, prefix the pull request title using one of the following:
BREAKING CHANGE: Significant changes that may affect compatibility
build: Changes that affect the build system or external dependencies
ci: Changes to our continuous integration processes or workflows
chore: Refactor, cleanup, or other non-functional code changes
docs: Documentation update or addition
feat: Introduces a new feature or enhancement to the codebase
fix: Bug fix or error correction
i18n: Internationalization or localization changes
perf: Performance improvement
refactor: Code restructuring for better maintainability, readability, or scalability
style: Changes that do not affect the meaning of the code (white space, formatting, missing semi-colons, etc.)
test: Adding missing tests or correcting existing tests
WIP: Work in progress, a temporary label for incomplete or ongoing work
Changelog Entry
Description
This pull request introduces a comprehensive, multi-layered theming system to Open WebUI, allowing for extensive customization of the user interface. The feature is centered around a new UI in the user settings modal and a robust set of Svelte stores and utility functions that handle everything from theme application to community theme management and automatic updates.
Added
Core Theming Infrastructure:
Entry Point (src/lib/theme.ts): A new barrel file that exports all theme-related functionalities from modularized files, providing a clean API for the rest of the application.
State Management (src/lib/stores/theme.ts):
themes: A Svelte store (Map<string, Theme>) initialized with default.json for built-in themes.
communityThemes: A store (Map<string, Theme>) for user-installed themes, persisted to localStorage.
currentThemeStore / liveThemeStore: Stores that hold the active and previewed theme objects, respectively.
themeUpdates / themeUpdateErrors: Stores that track available updates and fetch errors for community themes.
Theme Application (src/lib/themes/apply.ts):
Implements the core applyTheme(theme, isLiveUpdate) function which orchestrates the entire process of rendering a theme.
cleanupTheme(): A helper function that removes previously injected styles and CSS variables to ensure a clean slate before applying a new theme.
_applyGlobalThemeStyles(theme): A private function that handles injecting custom CSS, applying base theme variables, overriding with theme-specific variables, and setting <html> classes (.light, .dark, .oled-dark, .her).
Community Theme Logic (src/lib/themes/community.ts):
loadCommunityThemes(): Loads user themes from localStorage on startup.
saveCommunityThemes(): Persists the communityThemes store to localStorage with quota-exceeded error handling.
Implements the entire update mechanism via checkForThemeUpdates(), updateCommunityThemeFromUrl(), and isNewerVersion().
User Interface Components:
Main Settings UI (src/lib/components/chat/Settings/Themes.svelte):
The central component for all user-facing theme management.
Event Handlers: Contains logic for all user actions, including addThemeHandler (for URLs), importThemeFromFile, createNewTheme, saveTheme, copyTheme, and exportTheme.
Reactive UI: Uses Svelte's reactive statements ($:) to automatically filter (filteredThemes) and sort (sortedThemes) the list of themes as the user types or changes sort order.
A modal for creating a new theme or editing an existing one.
Provides a live preview by emitting an update event, which triggers applyTheme(..., true).
Includes generative tools for creating color palettes and gradients.
Confirmation & Warning Modals:
ThemeImportWarningModal.svelte: Warns the user if a theme's targetWebUIVersion does not match the current WebUI version.
ConfirmDialog.svelte: A generic confirmation dialog used for both deleting a theme and for displaying a security warning when a theme contains an animationScript.
This component now imports and calls applyTheme on mount to apply the user's saved theme.
It also calls checkForThemeUpdates to trigger the automatic update check in the background.
Deprecated
The previous method of setting a global "Chat Background Image" via a dedicated setting is now fully deprecated. This functionality is now exclusively handled by the chatBackgroundImageUrl property within a theme's theme.json.
Removed
The legacy UI for setting a global chat background image has been entirely removed from the settings panel in favor of the new, more flexible theming system.
Security
Arbitrary Code Execution Warning: The theme installation process in Themes.svelte now explicitly checks if a theme contains the animationScript property.
If it does, the ConfirmDialog.svelte modal is displayed, requiring the user to acknowledge the security risks of running arbitrary code from an untrusted source before the theme can be installed via the _finalizeAddTheme function.
Breaking Changes
BREAKING CHANGE: The global "Chat Background Image" setting is no longer available. Users who relied on this feature must now create or install a theme and set the chatBackgroundImageUrl property to achieve a similar effect. This change centralizes all appearance-related settings into the new theme.json schema, providing a more unified and powerful customization experience.
Additional Information
The feature is designed with a layering model (Base > Variables > Backgrounds > Animations > CSS) to allow for flexible and powerful customizations.
All theme settings are intentionally placed in the user-facing chat settings modal, as they are per-user preferences.
By submitting this pull request, I confirm that I have read and fully agree to the Contributor License Agreement (CLA), and I am providing my contributions under its terms.
🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.
## 📋 Pull Request Information
**Original PR:** https://github.com/open-webui/open-webui/pull/17396
**Author:** [@silentoplayz](https://github.com/silentoplayz)
**Created:** 9/12/2025
**Status:** ❌ Closed
**Base:** `dev` ← **Head:** `theming-expirmentaiton-part-2-(revamp)`
---
### 📝 Commits (10+)
- [`fb5a740`](https://github.com/open-webui/open-webui/commit/fb5a740f0026fcfc33b21026f96f90ffb46b0bdc) feat: Theming system
- [`9b141ac`](https://github.com/open-webui/open-webui/commit/9b141acf522c65c86e5ae1fd7b0214aa284bc5f0) feat: Add full theme schema to documentation
- [`9ddff46`](https://github.com/open-webui/open-webui/commit/9ddff46b83ff3eabf8123a931580eeab803b1a09) remove: unused const DEFAULT_PARTICLE_CONFIG
- [`8f93ce1`](https://github.com/open-webui/open-webui/commit/8f93ce12037ab0892761dd467783ea329ba05401) fix: base 'her'
- [`acc92d4`](https://github.com/open-webui/open-webui/commit/acc92d4e482ea196df2e519abe683d16dcb05748) feat: Replace theme import warning toast with confirmation modal
- [`b7ab4c0`](https://github.com/open-webui/open-webui/commit/b7ab4c0e8704ce71e26754519041db77e7f2f6ff) feat: Add random color generator to theme editor
- [`b042aa8`](https://github.com/open-webui/open-webui/commit/b042aa82d212ff73659fcca68b03763a770cea69) feat: Add gradient editor to theme customizer
- [`49ad0a8`](https://github.com/open-webui/open-webui/commit/49ad0a89b8724630ff7aac307ca2aa9915cc9522) feat: Add and enhance gradient editor in theme customizer
- [`6d923af`](https://github.com/open-webui/open-webui/commit/6d923af64b7aeb59583818c6fc490063852678c1) Update ThemeDocumentationModal.svelte
- [`3d03bd0`](https://github.com/open-webui/open-webui/commit/3d03bd06c97bd7bdb934c23dfb995d6905b9c3f2) Update ThemeEditorModal.svelte
### 📊 Changes
**65 files changed** (+7598 additions, -1116 deletions)
<details>
<summary>View changed files</summary>
📝 `package-lock.json` (+3552 -459)
📝 `package.json` (+10 -1)
📝 `src/app.css` (+14 -0)
📝 `src/lib/apis/auths/index.ts` (+1 -0)
📝 `src/lib/components/admin/Evaluations/Feedbacks.svelte` (+2 -2)
📝 `src/lib/components/admin/Evaluations/Leaderboard.svelte` (+2 -2)
📝 `src/lib/components/admin/Settings/Audio.svelte` (+4 -4)
📝 `src/lib/components/admin/Settings/CodeExecution.svelte` (+6 -6)
📝 `src/lib/components/admin/Settings/Connections/OllamaConnection.svelte` (+2 -2)
📝 `src/lib/components/admin/Settings/Connections/OpenAIConnection.svelte` (+1 -1)
📝 `src/lib/components/admin/Settings/Documents.svelte` (+9 -9)
📝 `src/lib/components/admin/Settings/General.svelte` (+1 -1)
📝 `src/lib/components/admin/Settings/Images.svelte` (+1 -1)
📝 `src/lib/components/admin/Settings/Interface/Banners.svelte` (+6 -3)
📝 `src/lib/components/admin/Settings/Pipelines.svelte` (+3 -3)
📝 `src/lib/components/admin/Settings/WebSearch.svelte` (+3 -3)
📝 `src/lib/components/admin/Users/Groups.svelte` (+1 -1)
📝 `src/lib/components/admin/Users/UserList.svelte` (+3 -3)
📝 `src/lib/components/channel/Navbar.svelte` (+0 -4)
📝 `src/lib/components/chat/Chat.svelte` (+5 -1)
_...and 45 more files_
</details>
### 📄 Description
# Pull Request Checklist
**Before submitting, make sure you've checked the following:**
- [X] **Target branch:** Please verify that the pull request targets the `dev` branch.
- [X] **Description:** Provide a concise description of the changes made in this pull request.
- [X] **Changelog:** Ensure a changelog entry following the format of [Keep a Changelog](https://keepachangelog.com/) is added at the bottom of the PR description.
- [X] **Documentation:** Have you updated relevant documentation [Open WebUI Docs](https://github.com/open-webui/docs), or other documentation sources?
- [X] **Dependencies:** Are there any new dependencies? Have you updated the dependency versions in the documentation?
- [X] **Testing:** Have you written and run sufficient tests to validate the changes?
- [X] **Code review:** Have you performed a self-review of your code, addressing any coding standard issues and ensuring adherence to the project's coding standards?
- [X] **Prefix:** To clearly categorize this pull request, prefix the pull request title using one of the following:
- **BREAKING CHANGE**: Significant changes that may affect compatibility
- **build**: Changes that affect the build system or external dependencies
- **ci**: Changes to our continuous integration processes or workflows
- **chore**: Refactor, cleanup, or other non-functional code changes
- **docs**: Documentation update or addition
- **feat**: Introduces a new feature or enhancement to the codebase
- **fix**: Bug fix or error correction
- **i18n**: Internationalization or localization changes
- **perf**: Performance improvement
- **refactor**: Code restructuring for better maintainability, readability, or scalability
- **style**: Changes that do not affect the meaning of the code (white space, formatting, missing semi-colons, etc.)
- **test**: Adding missing tests or correcting existing tests
- **WIP**: Work in progress, a temporary label for incomplete or ongoing work
# Changelog Entry
## Description
This pull request introduces a comprehensive, multi-layered theming system to Open WebUI, allowing for extensive customization of the user interface. The feature is centered around a new UI in the user settings modal and a robust set of Svelte stores and utility functions that handle everything from theme application to community theme management and automatic updates.
## Added
- **Core Theming Infrastructure:**
- **Entry Point (`src/lib/theme.ts`):** A new barrel file that exports all theme-related functionalities from modularized files, providing a clean API for the rest of the application.
- **State Management (`src/lib/stores/theme.ts`):**
- `themes`: A Svelte store (`Map<string, Theme>`) initialized with `default.json` for built-in themes.
- `communityThemes`: A store (`Map<string, Theme>`) for user-installed themes, persisted to `localStorage`.
- `currentThemeStore` / `liveThemeStore`: Stores that hold the active and previewed theme objects, respectively.
- `themeUpdates` / `themeUpdateErrors`: Stores that track available updates and fetch errors for community themes.
- **Theme Application (`src/lib/themes/apply.ts`):**
- Implements the core `applyTheme(theme, isLiveUpdate)` function which orchestrates the entire process of rendering a theme.
- `cleanupTheme()`: A helper function that removes previously injected styles and CSS variables to ensure a clean slate before applying a new theme.
- `_applyGlobalThemeStyles(theme)`: A private function that handles injecting custom CSS, applying base theme variables, overriding with theme-specific variables, and setting `<html>` classes (`.light`, `.dark`, `.oled-dark`, `.her`).
- **Community Theme Logic (`src/lib/themes/community.ts`):**
- `loadCommunityThemes()`: Loads user themes from `localStorage` on startup.
- `saveCommunityThemes()`: Persists the `communityThemes` store to `localStorage` with quota-exceeded error handling.
- Provides CRUD functions: `addCommunityTheme`, `updateCommunityTheme`, `removeCommunityTheme`.
- Implements the entire update mechanism via `checkForThemeUpdates()`, `updateCommunityThemeFromUrl()`, and `isNewerVersion()`.
- **User Interface Components:**
- **Main Settings UI (`src/lib/components/chat/Settings/Themes.svelte`):**
- The central component for all user-facing theme management.
- **Event Handlers:** Contains logic for all user actions, including `addThemeHandler` (for URLs), `importThemeFromFile`, `createNewTheme`, `saveTheme`, `copyTheme`, and `exportTheme`.
- **Reactive UI:** Uses Svelte's reactive statements (`$:`) to automatically filter (`filteredThemes`) and sort (`sortedThemes`) the list of themes as the user types or changes sort order.
- **Theme Editor (`src/lib/components/common/ThemeEditorModal.svelte`):**
- A modal for creating a new theme or editing an existing one.
- Provides a live preview by emitting an `update` event, which triggers `applyTheme(..., true)`.
- Includes generative tools for creating color palettes and gradients.
- **Confirmation & Warning Modals:**
- `ThemeImportWarningModal.svelte`: Warns the user if a theme's `targetWebUIVersion` does not match the current WebUI version.
- `ConfirmDialog.svelte`: A generic confirmation dialog used for both deleting a theme and for displaying a security warning when a theme contains an `animationScript`.
## Changed
- **Application Layout (`src/routes/(app)/+layout.svelte`):**
- This component now imports and calls `applyTheme` on mount to apply the user's saved theme.
- It also calls `checkForThemeUpdates` to trigger the automatic update check in the background.
## Deprecated
- The previous method of setting a global "Chat Background Image" via a dedicated setting is now fully deprecated. This functionality is now exclusively handled by the `chatBackgroundImageUrl` property within a theme's `theme.json`.
## Removed
- The legacy UI for setting a global chat background image has been entirely removed from the settings panel in favor of the new, more flexible theming system.
## Security
- **Arbitrary Code Execution Warning:** The theme installation process in `Themes.svelte` now explicitly checks if a theme contains the `animationScript` property.
- If it does, the `ConfirmDialog.svelte` modal is displayed, requiring the user to acknowledge the security risks of running arbitrary code from an untrusted source before the theme can be installed via the `_finalizeAddTheme` function.
## Breaking Changes
- BREAKING CHANGE: The global "Chat Background Image" setting is no longer available. Users who relied on this feature must now create or install a theme and set the `chatBackgroundImageUrl` property to achieve a similar effect. This change centralizes all appearance-related settings into the new `theme.json` schema, providing a more unified and powerful customization experience.
## Additional Information
- The feature is designed with a layering model (Base > Variables > Backgrounds > Animations > CSS) to allow for flexible and powerful customizations.
- All theme settings are intentionally placed in the user-facing chat settings modal, as they are per-user preferences.
- Documentation page pull request opened here - https://github.com/open-webui/docs/pull/693
### Screenshots or Videos
<img width="2553" height="1283" alt="image" src="https://github.com/user-attachments/assets/afbd5877-a0e6-40d9-9e85-eb01ca9119c0" />
<img width="981" height="1102" alt="image" src="https://github.com/user-attachments/assets/1584dce6-7d47-4d45-a922-937c06c49d94" />
<img width="567" height="855" alt="image" src="https://github.com/user-attachments/assets/96bdc44a-bc12-4638-9d17-b9f0f6e2e27f" />
<img width="945" height="620" alt="image" src="https://github.com/user-attachments/assets/533a5b35-ac0c-453c-85e3-38e641bd12bb" />
<img width="2307" height="1285" alt="image" src="https://github.com/user-attachments/assets/d947fad0-a57a-4c03-bdb4-7ff003d4bf83" />
<img width="951" height="832" alt="image" src="https://github.com/user-attachments/assets/19669da2-67b4-4d7d-8535-e3bc52beb1ad" />
<img width="967" height="622" alt="image" src="https://github.com/user-attachments/assets/8dd66204-4318-4db3-9c4f-c8a4d4754417" />
<img width="2302" height="1282" alt="image" src="https://github.com/user-attachments/assets/eec6379d-280b-4466-b304-5ca8f3f7e776" />
<img width="1079" height="725" alt="image" src="https://github.com/user-attachments/assets/af4766ec-5313-43f9-a92a-7f7009255d67" />
<img width="951" height="832" alt="image" src="https://github.com/user-attachments/assets/d1cab0b0-dae0-4453-9b31-76f9e44012bc" />
<img width="415" height="212" alt="image" src="https://github.com/user-attachments/assets/88c9689e-26a5-47f2-8214-26e6fda764e7" />
<img width="957" height="629" alt="image" src="https://github.com/user-attachments/assets/04b8a99e-a0df-4794-aa1f-b3b016e5c567" />
<img width="957" height="629" alt="image" src="https://github.com/user-attachments/assets/e38e0430-55e3-4c39-91e4-6546fe4b9e0a" />
<img width="897" height="591" alt="image" src="https://github.com/user-attachments/assets/cf17cf9a-2f17-4ad5-9092-04cb7d735d69" />
<img width="957" height="629" alt="image" src="https://github.com/user-attachments/assets/7f5b2220-3c44-43ff-83fa-dc226f68213d" />
<img width="957" height="629" alt="image" src="https://github.com/user-attachments/assets/b93bef8d-0f8c-4792-97da-5c4fd3f60677" />
### Contributor License Agreement
By submitting this pull request, I confirm that I have read and fully agree to the [Contributor License Agreement (CLA)](https://github.com/open-webui/open-webui/blob/main/CONTRIBUTOR_LICENSE_AGREEMENT), and I am providing my contributions under its terms.
---
<sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
📋 Pull Request Information
Original PR: https://github.com/open-webui/open-webui/pull/17396
Author: @silentoplayz
Created: 9/12/2025
Status: ❌ Closed
Base:
dev← Head:theming-expirmentaiton-part-2-(revamp)📝 Commits (10+)
fb5a740feat: Theming system9b141acfeat: Add full theme schema to documentation9ddff46remove: unused const DEFAULT_PARTICLE_CONFIG8f93ce1fix: base 'her'acc92d4feat: Replace theme import warning toast with confirmation modalb7ab4c0feat: Add random color generator to theme editorb042aa8feat: Add gradient editor to theme customizer49ad0a8feat: Add and enhance gradient editor in theme customizer6d923afUpdate ThemeDocumentationModal.svelte3d03bd0Update ThemeEditorModal.svelte📊 Changes
65 files changed (+7598 additions, -1116 deletions)
View changed files
📝
package-lock.json(+3552 -459)📝
package.json(+10 -1)📝
src/app.css(+14 -0)📝
src/lib/apis/auths/index.ts(+1 -0)📝
src/lib/components/admin/Evaluations/Feedbacks.svelte(+2 -2)📝
src/lib/components/admin/Evaluations/Leaderboard.svelte(+2 -2)📝
src/lib/components/admin/Settings/Audio.svelte(+4 -4)📝
src/lib/components/admin/Settings/CodeExecution.svelte(+6 -6)📝
src/lib/components/admin/Settings/Connections/OllamaConnection.svelte(+2 -2)📝
src/lib/components/admin/Settings/Connections/OpenAIConnection.svelte(+1 -1)📝
src/lib/components/admin/Settings/Documents.svelte(+9 -9)📝
src/lib/components/admin/Settings/General.svelte(+1 -1)📝
src/lib/components/admin/Settings/Images.svelte(+1 -1)📝
src/lib/components/admin/Settings/Interface/Banners.svelte(+6 -3)📝
src/lib/components/admin/Settings/Pipelines.svelte(+3 -3)📝
src/lib/components/admin/Settings/WebSearch.svelte(+3 -3)📝
src/lib/components/admin/Users/Groups.svelte(+1 -1)📝
src/lib/components/admin/Users/UserList.svelte(+3 -3)📝
src/lib/components/channel/Navbar.svelte(+0 -4)📝
src/lib/components/chat/Chat.svelte(+5 -1)...and 45 more files
📄 Description
Pull Request Checklist
Before submitting, make sure you've checked the following:
devbranch.Changelog Entry
Description
This pull request introduces a comprehensive, multi-layered theming system to Open WebUI, allowing for extensive customization of the user interface. The feature is centered around a new UI in the user settings modal and a robust set of Svelte stores and utility functions that handle everything from theme application to community theme management and automatic updates.
Added
Core Theming Infrastructure:
src/lib/theme.ts): A new barrel file that exports all theme-related functionalities from modularized files, providing a clean API for the rest of the application.src/lib/stores/theme.ts):themes: A Svelte store (Map<string, Theme>) initialized withdefault.jsonfor built-in themes.communityThemes: A store (Map<string, Theme>) for user-installed themes, persisted tolocalStorage.currentThemeStore/liveThemeStore: Stores that hold the active and previewed theme objects, respectively.themeUpdates/themeUpdateErrors: Stores that track available updates and fetch errors for community themes.src/lib/themes/apply.ts):applyTheme(theme, isLiveUpdate)function which orchestrates the entire process of rendering a theme.cleanupTheme(): A helper function that removes previously injected styles and CSS variables to ensure a clean slate before applying a new theme._applyGlobalThemeStyles(theme): A private function that handles injecting custom CSS, applying base theme variables, overriding with theme-specific variables, and setting<html>classes (.light,.dark,.oled-dark,.her).src/lib/themes/community.ts):loadCommunityThemes(): Loads user themes fromlocalStorageon startup.saveCommunityThemes(): Persists thecommunityThemesstore tolocalStoragewith quota-exceeded error handling.addCommunityTheme,updateCommunityTheme,removeCommunityTheme.checkForThemeUpdates(),updateCommunityThemeFromUrl(), andisNewerVersion().User Interface Components:
src/lib/components/chat/Settings/Themes.svelte):addThemeHandler(for URLs),importThemeFromFile,createNewTheme,saveTheme,copyTheme, andexportTheme.$:) to automatically filter (filteredThemes) and sort (sortedThemes) the list of themes as the user types or changes sort order.src/lib/components/common/ThemeEditorModal.svelte):updateevent, which triggersapplyTheme(..., true).ThemeImportWarningModal.svelte: Warns the user if a theme'stargetWebUIVersiondoes not match the current WebUI version.ConfirmDialog.svelte: A generic confirmation dialog used for both deleting a theme and for displaying a security warning when a theme contains ananimationScript.Changed
src/routes/(app)/+layout.svelte):applyThemeon mount to apply the user's saved theme.checkForThemeUpdatesto trigger the automatic update check in the background.Deprecated
chatBackgroundImageUrlproperty within a theme'stheme.json.Removed
Security
Themes.sveltenow explicitly checks if a theme contains theanimationScriptproperty.ConfirmDialog.sveltemodal is displayed, requiring the user to acknowledge the security risks of running arbitrary code from an untrusted source before the theme can be installed via the_finalizeAddThemefunction.Breaking Changes
chatBackgroundImageUrlproperty to achieve a similar effect. This change centralizes all appearance-related settings into the newtheme.jsonschema, providing a more unified and powerful customization experience.Additional Information
Screenshots or Videos
Contributor License Agreement
By submitting this pull request, I confirm that I have read and fully agree to the Contributor License Agreement (CLA), and I am providing my contributions under its terms.
🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.