feat: add ColorScheme API for light/dark theme support #22718

Artur- · 2025-11-12T14:15:41Z

Adds a ColorScheme API for controlling light and dark theme variants in Vaadin applications. Includes an @colorscheme annotation for initial configuration and Page.setColorScheme() for runtime switching. Uses the HTML theme attribute approach for CSS compatibility.

Initial Configuration

@colorscheme annotation for AppShell to set the initial color scheme
Applied as inline style on element during bootstrap

Runtime Control

Page.setColorScheme(ColorScheme.Value) / Page.getColorScheme() for dynamic switching
ColorScheme.Value enum: LIGHT, DARK, LIGHT_DARK, DARK_LIGHT, NORMAL
Server-side state synchronized via ExtendedClientDetails

Implementation Details

Sets theme attribute on element (e.g., )
Clears inline style.colorScheme to allow theme CSS to set the property
Enables CSS selectors: html[theme~="dark"] { color-scheme: dark; }
Client sends color scheme to server via v-cs parameter in Flow.ts
Automatic string-to-enum conversion via ColorScheme.Value.fromString()

Backward Compatibility

Deprecated @theme(variant) attribute in favor of @colorscheme
Existing variant usage continues to work

Fixes #15354

github-actions · 2025-11-12T14:31:37Z

Test Results

1 296 files + 4 1 296 suites +4 1h 16m 49s ⏱️ + 1m 11s
9 077 tests +31 9 009 ✅ +31 68 💤 ±0 0 ❌ ±0
9 533 runs +26 9 457 ✅ +26 76 💤 ±0 0 ❌ ±0

Results for commit 7ce5642. ± Comparison against base commit 8a177ec.

♻️ This comment has been updated with latest results.

jouni · 2025-11-12T19:07:58Z

Rather than making it work differently with Lumo and Aura, we should align the themes to work the same way. Either both offer a theme="dark|light" attribute or both support the color-scheme property on the html element.

Artur- · 2025-11-12T19:35:48Z

Please do

Artur- · 2025-11-12T19:38:13Z

vaadin/web-components#10484

Adds Page.setThemeVariant() and Page.getThemeVariant() methods to enable runtime switching between theme variants without requiring manual JavaScript execution. The theme variant is automatically synced from the browser on page load if set in index.html. The implementation supports both Lumo and Aura themes: - Lumo: Sets/removes the 'theme' attribute on the HTML element - Aura: Sets/removes the '--aura-color-scheme' CSS custom property Key changes: - Page API: setThemeVariant() and getThemeVariant() methods - UIInternals: cache theme variant for quick access (returns "" not null) - ExtendedClientDetails: include theme variant from browser - FlowBootstrap.js: sync theme attribute and Aura color scheme on page load - Comprehensive unit and integration tests Fixes #15354

flow-client/src/main/frontend/Flow.ts

...sts/test-root-context/src/main/java/com/vaadin/flow/uitest/ui/ExtendedClientDetailsView.java

flow-server/src/test/java/com/vaadin/flow/component/page/PageTest.java

flow-client/src/main/frontend/Flow.ts

jouni

Change request concerning the use of --aura-color-scheme which no longer exists.

Why do we need the theme name? It’ll be an empty string for any custom theme not built on top of Lumo or Aura. I feel this feature should be a simple theme-agnostic way of setting attribute values on the <html> document element.

Given the discussion about possibly moving away from the theme attribute in future major versions (correct me if I remember wrong, @rolfsmeds and @web-padawan), I’m unsure if we should build more API explicitly for that.

The themeVariant field in ExtendedClientDetails is null until first initialized, consistent with other fields like windowName. Added null check in Page.getThemeVariant() to ensure it always returns an empty string instead of null when the theme variant hasn't been set yet.

Artur- · 2025-11-18T07:49:29Z

Given the discussion about possibly moving away from the theme attribute in future major versions (correct me if I remember wrong, @rolfsmeds and @web-padawan), I’m unsure if we should build more API explicitly for that.

What does this refer to? The API added is for getting the variant: dark or light. It can be set using an attribute or using magic fairy dust and this API stays the same

Artur- · 2025-11-18T07:50:51Z

Why do we need the theme name? It’ll be an empty string for any custom theme not built on top of Lumo or Aura.

Depends on who "we" are. Some add-on authors will presumably use it to customize some behavior to better match Aura or Lumo defaults, and use either one as the fallback if you have a completely custom theme.

The --aura-color-scheme CSS custom property has been replaced with the native color-scheme property in Aura theme. Updated the fallback logic to check for the standard color-scheme property when the theme attribute is not present.

Artur- · 2025-11-20T16:42:19Z

Changed the whole API to be based on ColorScheme instead of ThemeVariant

Artur- · 2025-11-20T16:44:29Z

Component level API in #22799

@colorscheme

- IndexHtmlRequestHandler now sets theme attribute instead of inline style - Updated PageTest to check for theme attribute and style clearing - Both @colorscheme and @theme(variant) now set theme attribute consistently - All tests pass

flow-server/src/main/java/com/vaadin/flow/component/page/Page.java

jouni · 2025-11-21T08:30:14Z

But what is SYSTEM? Do you mean NORMAL which is a valid CSS value?

"System" is sometimes/often used to indicate light dark, aka "auto", aka "operating system preference". It’s different from normal, which is the default/initial value of the browser, which allows the color scheme to be defined by the meta tag. If there’s no meta tag, then normal results in light mode.

The color-scheme CSS property is essentially a way to override the meta tag value.

flow-server/src/main/java/com/vaadin/flow/component/page/ColorScheme.java

flow-server/src/main/java/com/vaadin/flow/component/page/Page.java

NORMAL doesn't force browser default behavior - it just means no color scheme is set via this API. The actual behavior depends on other factors like browser defaults, system preferences, or meta tags.

Addresses review feedback - sets both theme attribute and color-scheme property to support custom themes that don't define their own CSS rules. The theme attribute enables CSS targeting (html[theme~='dark']), while the inline color-scheme property ensures browser UI adaptation works universally, even for custom themes. - Updated Page.java to set property instead of clearing it - Updated documentation to explain dual-setting approach - Updated all tests to verify both attribute and property - All integration tests passing (6/6)

For multi-value color schemes like LIGHT_DARK, the theme attribute now uses hyphens (e.g., "light-dark") while the CSS color-scheme property uses spaces (e.g., "light dark"). - Added getThemeValue() method to ColorScheme.Value enum - Updated Page.setColorScheme() to pass separate values for theme attribute and CSS property - Updated IndexHtmlRequestHandler to use getThemeValue() - Added ColorSchemeTest to verify enum behavior - Updated PageTest with test for LIGHT_DARK handling - All unit and integration tests passing

Artur- · 2025-11-21T12:02:09Z

Let's wait for @jouni then

sonarqubecloud · 2025-11-21T14:46:59Z

Quality Gate passed

Issues
135 New issues
1 Accepted issue

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

vaadin-bot · 2025-11-28T12:50:52Z

This ticket/PR has been released with Vaadin 25.0.0-beta8.

github-actions bot added the +1.0.0 label Nov 12, 2025

vaadin deleted a comment from github-actions bot Nov 12, 2025

Artur- force-pushed the flow-change-dark branch from fa58500 to 4b6d9a3 Compare November 12, 2025 20:24

sissbruecker mentioned this pull request Nov 13, 2025

feat: allow switching between light/dark Aura theme with theme attribute vaadin/web-components#10486

Merged

mshabarov requested a review from caalador November 17, 2025 12:45

Artur- force-pushed the flow-change-dark branch 2 times, most recently from d97b63b to ec54cee Compare November 17, 2025 14:00

github-actions bot added +0.1.0 and removed +1.0.0 labels Nov 17, 2025

vaadin-bot added +1.0.0 and removed +0.1.0 labels Nov 17, 2025

Artur- force-pushed the flow-change-dark branch from ec54cee to a228ebb Compare November 17, 2025 14:31

Artur- marked this pull request as ready for review November 17, 2025 14:31

github-actions bot added +0.1.0 and removed +1.0.0 labels Nov 17, 2025

vaadin-bot added +1.0.0 and removed +0.1.0 labels Nov 17, 2025

caalador reviewed Nov 18, 2025

View reviewed changes

Use short name

56cd091

jouni reviewed Nov 18, 2025

View reviewed changes

flow-client/src/main/frontend/Flow.ts Outdated Show resolved Hide resolved

jouni requested changes Nov 18, 2025

View reviewed changes

Artur- changed the title ~~feat: add ColorScheme (light/dark) API for runtime theme switching~~ feat: add ColorScheme API for light/dark theme support Nov 20, 2025

Artur- added 2 commits November 20, 2025 18:41

Update comment

210eb83

Merge remote-tracking branch 'origin/main' into flow-change-dark

3c0f595

vaadin deleted a comment from github-actions bot Nov 20, 2025

Artur- added 2 commits November 20, 2025 18:48

format

6f18a10

Artur- requested review from caalador and jouni November 21, 2025 07:39

Merge branch 'main' into flow-change-dark

8b5bf5a

caalador reviewed Nov 21, 2025

View reviewed changes

flow-server/src/main/java/com/vaadin/flow/component/page/Page.java Outdated Show resolved Hide resolved

jouni reviewed Nov 21, 2025

View reviewed changes

flow-server/src/main/java/com/vaadin/flow/component/page/ColorScheme.java Outdated Show resolved Hide resolved

flow-server/src/main/java/com/vaadin/flow/component/page/Page.java Outdated Show resolved Hide resolved

Artur- added 2 commits November 21, 2025 11:01

docs: clarify NORMAL color scheme behavior

6d3277b

NORMAL doesn't force browser default behavior - it just means no color scheme is set via this API. The actual behavior depends on other factors like browser defaults, system preferences, or meta tags.

vaadin deleted a comment from github-actions bot Nov 21, 2025

caalador approved these changes Nov 21, 2025

View reviewed changes

Merge branch 'main' into flow-change-dark

7ce5642

jouni self-requested a review November 24, 2025 07:32

jouni approved these changes Nov 24, 2025

View reviewed changes

Artur- merged commit ad035c3 into main Nov 24, 2025
34 checks passed

Artur- deleted the flow-change-dark branch November 24, 2025 07:50

This was referenced Nov 24, 2025

docs: changing color scheme vaadin/docs#4817

Merged

refactor: remove theme attribute color scheme rules vaadin/web-components#10541

Merged

vaadin-bot added the Released with Vaadin 25.0.0-beta8 label Nov 28, 2025

feat: add ColorScheme API for light/dark theme support #22718

feat: add ColorScheme API for light/dark theme support #22718

Conversation

Artur- commented Nov 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Nov 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Test Results

Uh oh!

jouni commented Nov 12, 2025

Uh oh!

Artur- commented Nov 12, 2025

Uh oh!

Artur- commented Nov 12, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jouni left a comment

Choose a reason for hiding this comment

Uh oh!

Artur- commented Nov 18, 2025

Uh oh!

Artur- commented Nov 18, 2025

Uh oh!

Artur- commented Nov 20, 2025

Uh oh!

Artur- commented Nov 20, 2025

Uh oh!

Uh oh!

jouni commented Nov 21, 2025

Uh oh!

Uh oh!

Uh oh!

Artur- commented Nov 21, 2025

Uh oh!

sonarqubecloud bot commented Nov 21, 2025

Quality Gate passed

Uh oh!

Uh oh!

vaadin-bot commented Nov 28, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

Artur- commented Nov 12, 2025 •

edited

Loading

github-actions bot commented Nov 12, 2025 •

edited

Loading