github-starred/open-webui
2
0
Fork 0
mirror of https://github.com/open-webui/open-webui.git synced 2026-03-14 11:05:45 -05:00
Code Issues 308 Packages Projects Releases 100 Wiki Activity

[PR #17396] [CLOSED] feat: Theming system #11211

New Issue
Closed
opened 2025-11-11 19:25:43 -06:00 by GiteaMirror · 0 comments
GiteaMirror commented 2025-11-11 19:25:43 -06:00
Owner
Copy Link

📋 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+)

  • fb5a740 feat: Theming system
  • 9b141ac feat: Add full theme schema to documentation
  • 9ddff46 remove: unused const DEFAULT_PARTICLE_CONFIG
  • 8f93ce1 fix: base 'her'
  • acc92d4 feat: Replace theme import warning toast with confirmation modal
  • b7ab4c0 feat: Add random color generator to theme editor
  • b042aa8 feat: Add gradient editor to theme customizer
  • 49ad0a8 feat: Add and enhance gradient editor in theme customizer
  • 6d923af Update ThemeDocumentationModal.svelte
  • 3d03bd0 Update 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:

  • 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.
      • 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

image image image image image image image image image image image image image image image image

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.

## 📋 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>
GiteaMirror added the pull-request label 2025-11-11 19:25:43 -06:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
core
documentation
enhancement
good first issue
help wanted
non-core
pull-request
Mirrored from GitHub Pull Request
 python
question
testing wanted
No Label pull-request
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
GiteaMirror ninjasurge
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: github-starred/open-webui#11211
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?