Repository navigation
Description
Description
An application that chooses its theme at runtime adds and removes stylesheets through Page. Two things go wrong.
The order is not stable. Two sheets added with page.addStyleSheet, then one of them replaced: the surviving sheet sometimes ends up after the new one and sometimes before. Nothing in the API orders them.
Removing a sheet and adding the same URL back in one round trip loses it. registration.remove() followed by page.addStyleSheet(sameUrl) in the same server visit leaves the page with no sheet at all. The two operations reach the browser together and the add is treated as a duplicate of a sheet that is still there. Nothing is logged.
Why it matters
The first one produces colours that are right in one theme and wrong in the other, depending on which sheet happened to land last, which is a bug nobody can reproduce on demand.
The second one is worse: switching between two themes that share a sheet leaves the application unstyled, and the only clue is that it comes back after a reload.
Expected
For the order: a documented order, or a way to say where a sheet goes.
For the re-add: treat a removal and an addition of the same URL in one round trip as a replacement, or log that the addition was dropped.
Workaround
Win on specificity instead of order: html:root beats the plain html both themes use. And never touch what does not change: keep the shared sheet loaded and swap only the other one.
Reproduce
The re-add half is in 38-dark-mode.zip, route /swap. mvn spring-boot:run, then http://localhost:8138/swap and press the buttons in order, listing link[rel=stylesheet] after each one:
| After | Sheets on the page |
|---|---|
| load | lumo.css aura.css |
remove() and addStyleSheet(same URL) in one round trip |
aura.css |
remove() alone |
aura.css |
addStyleSheet(same URL) in its own round trip |
lumo.css aura.css |
Row two is the bug: the sheet is gone and the add that was meant to bring it back did nothing. Row four is the same call, one round trip later, working. Nothing is logged in either case.
sheet.remove();
sheet = page.addStyleSheet(Lumo.STYLESHEET); // dropped as a duplicateThe order half is not reduced. It is real in an application that swaps two sheets, and it depends on which sheet happens to land last, so there is nothing here that reproduces it on demand. Treat it as the observation that the API says nothing about order.
Getting the project
38-dark-mode.zip, 4 KB, sources only. Unzip it and:
mvn spring-boot:run
Found on 25.3.0-beta1.
Activity
totally-not-ai commentedon Sep 9, 2026
Looked into this. The re-add half is a real bug with a definite root cause on the client, and there is a fix for it in #25594. The order half is partly a symptom of the same bug and partly a genuine API gap — I left that one for a decision rather than guessing.
1.
remove()+addStyleSheet(sameUrl)in one round trip loses the sheet — real bugThe server does its part correctly.
Registration.remove()goes toUIInternals.removeStyleSheet(id), which queues the id inpendingStyleSheetRemovalsand drops the URL from theDependencyList(urlCache,urlToLoadedDependency,sentToClient). Thepage.addStyleSheet(url)that follows therefore finds no existing dependency for that URL, mints a fresh id, and ends up ingetPendingSendToClient(). So the UIDL that goes out carries both halves:{ "EAGER": [ { "type": "STYLESHEET", "url": ".../lumo.css", "id": "<new-id>" } ], "stylesheetRemovals": [ "<old-id>" ] }The client is where the add is lost.
MessageHandlerloads the message's dependencies first, and processesstylesheetRemovalslater, insideprocessMessage, which is itself deferred until the eager dependencies have loaded:flow-client/src/main/frontend/internal/client/communication/MessageHandler.ts—#handleDependencies(valueMap), thenrunWhenEagerDependenciesLoaded(() => #processMessage(...)), and#processStylesheetRemovalssits inside#processMessage.flow-client/src/main/java/com/vaadin/client/communication/MessageHandler.java— same order.So the add reaches
ResourceLoader.loadStylesheet, which dedupes by URL:isLoaded(url)is stilltrue, because the<link>that is about to be removed is still on the page and still in the loader's loaded-resources set. The loader notifies the listener and creates no element. Only then does the removal run and delete that<link>, andclearLoadedResourceByIddrops the URL from the loaded set. Net result: no sheet on the page, nothing logged. One round trip later the very same call works (row four of the table) precisely because that last step has meanwhile freed the URL.Worth noting the same mechanism can bite the CSS hotswapper:
StyleSheetHotswapperapplies its removals and its adds in one pass, so a URL that is both removed and re-added in one pass disappears the same way.Fix
Apply a message's
stylesheetRemovalsbefore loading the dependencies that same message carries, in both clients. Then the add is a real add — a fresh<link data-id="<new-id>">— which is exactly the "treat a removal and an addition of the same URL in one round trip as a replacement" behaviour asked for, and theRegistrationreturned by the secondaddStyleSheetrefers to the element that is actually on the page. No API change, no new UIDL key, and removal-only and add-only round trips are unaffected (a removal-only message has no eager dependency to wait for, so the timing is the same as today).#25594 has that change plus a unit test that wires the real
ResourceLoader/DependencyLoaderand fails without it (it reproduces the "page ends up with neither" outcome), a matching GWT case, and an IT on the existingStyleRemovalView/StyleRemovalIT.2. The order
Two separate things here.
The instability described looks like this same bug. Adds are deterministic today:
DependencyListkeeps aLinkedHashMap,UidlWriterpreserves that order per load mode, and the client inserts each<link>before the<!--Stylesheet end-->comment in<head>, in arrival order. So a sheet added later lands after one added earlier, and a re-added URL moves to the end. The "sometimes before, sometimes after" is what you get when the re-add sometimes takes effect (new sheet appended last) and sometimes is silently dropped (survivor keeps its original position) — i.e. bug 1. With bug 1 fixed, a swap is deterministic: the re-added sheet is always last.What is genuinely missing is the promise and the control, and that needs a product/API decision rather than a patch from me:
Page.addStyleSheet— sheets are inserted in the order they are added, and re-adding a URL moves it to the end. Cheapest option; costs nothing but commits Flow to the current order.addJavaScript).My recommendation is 1 now and 2 only if there is demand, but that is a call for someone else.
One small related wart I did not touch:
UIInternals.getPendingStyleSheetRemovals()copies aLinkedHashSetinto aHashSet, so removal ids reach the client in arbitrary order. It cannot reorder the surviving sheets (removing an element does not move its siblings), so it is not the cause of anything here, but the ordering is lost for no reason./cc
@manolofix(flow-client): apply a message's stylesheet removals before its ad…
vaadin-bot commentedon Sep 14, 2026
This ticket/PR has been released with Vaadin 25.3.0-beta3.
fix(flow-client): apply a message's stylesheet removals before its ad…
vaadin-bot commentedon Sep 29, 2026
This ticket/PR has been released with Vaadin 25.4.0-alpha1.