Theming and Customization
Relevant source files
The following files were used as context for generating this wiki page:
Theming and Customization in Casdoor allows administrators to tailor the visual identity of the platform at both the organization and application levels. This system leverages Ant Design's ConfigProvider and custom theme tokens to control primary colors, border radii, and layout algorithms (such as dark or compact modes). The goal is to provide a seamless white-label experience for different tenants.
The system supports granular control over UI elements including login panels, headers, footers, and custom CSS injections. This ensures that every user-facing interface, from the main management console to the specific application login pages, reflects the branding requirements of the host organization.
Sources: web/src/common/theme/ThemeEditor.js:46-70, web/src/Setting.js:48-56, web/src/App.js:203-228
Theme Hierarchy and Resolution
Casdoor employs a hierarchical resolution strategy for themes. The system first checks if an application has a customized theme enabled. If not, it falls back to the organization's theme settings. If neither is specified or enabled, it defaults to the system-wide default configuration.
The following flowchart illustrates the resolution logic used by the getThemeData utility:
The getThemeData function ensures that specific application branding takes precedence over broader organization styles.
Sources: web/src/Setting.js:48-56, web/src/ApplicationEditPage.js:698-710
Core Theming Components
ThemeEditor
The ThemeEditor component provides a unified interface for modifying theme tokens. It utilizes Ant Design's Form to manage fields like themeType, colorPrimary, borderRadius, and isCompact. It dynamically updates the ConfigProvider algorithm based on the selected theme type (Light vs. Dark) and density (Standard vs. Compact).
Key pre-defined theme configurations include:
| Theme Type | Primary Color | Border Radius | Algorithm |
|---|---|---|---|
default | System Default | 2 (Dark) | defaultAlgorithm |
dark | System Default | 2 | darkAlgorithm |
lark | GREEN_COLOR | 4 | defaultAlgorithm |
comic | PINK_COLOR | 16 | defaultAlgorithm |
Sources: web/src/common/theme/ThemeEditor.js:25-40, web/src/common/theme/ThemeEditor.js:42-100
ThemePicker and ColorPicker
ThemePicker allows users to select from visual presets (default, dark, lark, comic) using SVG previews. ColorPicker provides specialized color constants such as GREEN_COLOR (#2dbd68) and PINK_COLOR (#eb2f96) alongside a selection interface.
Sources: web/src/common/theme/ThemePicker.js:25-30, web/src/common/theme/ColorPicker.js
UI Customization at Organization Level
Organizations serve as the primary containers for shared branding. Customization options available at this level include logos (light and dark variants), favicons, and localized footer content.
| Configuration Field | Description | Source File |
|---|---|---|
logo | URL for the primary organization logo. | web/src/OrganizationEditPage.js:160-165 |
logoDark | URL for the logo used in dark mode. | web/src/OrganizationEditPage.js:175-180 |
favicon | Icon displayed in browser tabs. | web/src/OrganizationEditPage.js:205-210 |
navItems | Configures visible sidebar/navigation elements for admins. | web/src/OrganizationEditPage.js:450-460 |
userNavItems | Configures visible navigation elements for normal users. | web/src/OrganizationEditPage.js:465-475 |
Sources: web/src/OrganizationEditPage.js:145-520
Application-Specific Customization
Applications allow for even more specific UI overrides, particularly for the Sign-in and Sign-up pages. This includes background images, custom CSS, and the positioning of the login form.
Form Layout and CSS Injection
Administrators can control the positioning of the login form using the formOffset property.
- Left (1): 0 10% margin.
- Center (2): 0 auto margin.
- Right (3): 0 60% margin.
- Side Panel (4): Enables a side panel with custom HTML (
formSideHtml).
Custom CSS strings are injected directly into the page through dangerouslySetInnerHTML to allow for deep styling of the login container.
Sources: web/src/Setting.js:1115-1135, web/src/ApplicationEditPage.js:630-680
HTML and Content Overrides
Applications can override default HTML blocks to change the user experience:
- Header/Footer HTML: Custom snippets for the top and bottom of the auth pages.
- Terms of Use: Supports uploading
.htmlfiles for legal compliance links. - Signin/Signup Items: Table-driven configuration of which fields (e.g., Email, Username, Password) are visible or required.
Sources: web/src/ApplicationEditPage.js:180-200, web/src/ApplicationEditPage.js:710-750
Implementation Architecture
The core application (App.js) listens for theme changes and wraps the entire management UI in a ConfigProvider. It resolves the theme algorithm by mapping string identifiers to Ant Design constants.
The getAlgorithm function maps the "dark" name to theme.darkAlgorithm and "compact" to theme.compactAlgorithm.
Sources: web/src/Setting.js:58-69, web/src/App.js:440-460
Summary
Theming and customization in Casdoor is a multi-layered system that balances ease of use through presets with deep flexibility via raw CSS and HTML injection. By defining themes at the organization level and allowing overrides at the application level, Casdoor enables complex multi-tenant environments to maintain unique branding across all user touchpoints.
Sources: web/src/Setting.js:48-56, web/src/ApplicationEditPage.js:698-760