fineui-theming

FineUI Theme Setting and Switching

Starting from v15, the theme system was refactored from SCSS precompilation to CSS Variables: at runtime you only need to load themes/{主题}/theme.css to override color variables, with no need for sass.

When to Use

• Set the site-wide global theme
• Let users switch themes at runtime (dropdown/wall of images)
• Apply an already generated custom theme; when creating a new color scheme use fineui-custom-theme

Built-in Themes

Theme enum (use Pascal names in configuration, lowercase in F.js):

• Pure series：Pure_Black(default),Pure_Green、Pure_Blue、Pure_Purple、Pure_Orange
• jQuery UI series：Cupertino、Start、Dark_Hive、Flick、South_Street
• Also chinese_red etc.; dark themes such as Dark_Hive。

Set the Global Theme (Quick Overview)

// ① F.js —— F.init 里设初始主题（小写）
F.init({ theme: 'pure_black' });

<!-- ② Pro（WebForms）—— Web.config 的 <FineUI.Pro> 段 -->
<FineUI.Pro DebugMode="false" Theme="Pure_Black" EnableAnimation="true" />

// ③ Core（MVC / RazorForms / RazorPages 三套一致）—— appsettings.json
"FineUI": { "Theme": "Pure_Black", "EnableAnimation": true }

# ④ FineUI.Java（Spring Boot）—— application.properties 的 fineui.* 键（键名 kebab-case、主题名小写）
fineui.theme=pure_black
fineui.enable-animation=true

The Java global default is in application.properties; for page-level/per-user switching implement FineUIPageManagerInitializer bean（pm.theme(...)), see references/set-theme.md。Theme CSS variables are fully consistent with F.js(the same set of themes/{主题}/theme.css）。

Reference Documentation

File	When to Read
references/set-theme.md	Global default, PageManager override, runtime switching (Cookie + refresh)
references/custom-theme.md	Files, directories, and integration entry points for custom themes

Related Skills

• fineui-foundation: page skeleton (_Layout / PageManager location)
• fineui-custom-theme: create, generate, validate, and deliver custom themes

Constraints and Rules

1. Theme name casing: C# configuration/enum uses Pure_Black(Pascal + underscore); F.js F.init({ theme: 'pure_black' }) uses lowercase;Java application.properties uses lowercase fineui.theme=pure_black（themes/ directory names are lowercase, casing is insensitive).
2. Global default entry point: Pro goes through Web.config of <FineUI.Pro Theme=".."/>; the three Core sets go through appsettings.json of "FineUI":{"Theme":".."}；Java goes through application.properties of fineui.theme=..（fineui.* key, kebab-case)。
3. There is no F.setTheme public method: examples commonly usewrite Theme Cookie → refresh the page → the server reads the Cookie and sets PageManager. Applications need to distinguish between built-in and custom themes; the Java example's current Cookie handling only calls pm.theme(...), and when using custom themes the existing initializer needs to be extended. See references/set-theme.md。
4. Do not manually modify theme.cssfor custom themes: after modifying theme.config , use the application's res/themes built-in generate-theme.mjs to generate. The public examples for Pro, Core, and Java all provide generators. Java custom themes are referenced through pm.customTheme(...) , and cannot be replaced by fineui.theme or pm.theme(...) .
5. Dark theme：is-dark-background = true controls the derived styles at generation time, is not equivalent to the client-side F.isDarkTheme, and does not guarantee automatic addition of the f-theme-darkbg class.

Official Resources

• Online documentation and theme preview:https://www.fineui.com/
• Application-side generation command: in the res/themes directory with the generator, execute node generate-theme.mjs 主题名