Title: feat(core): let applications merge the classes of an element before they are written (provideClassMerge) · Issue #72094 · angular/angular · GitHub
Open Graph Title: feat(core): let applications merge the classes of an element before they are written (provideClassMerge) · Issue #72094 · angular/angular
X Title: feat(core): let applications merge the classes of an element before they are written (provideClassMerge) · Issue #72094 · angular/angular
Description: Which @angular/* package(s) are relevant/related to the feature request? core Description Utility CSS frameworks make two different class names conflict: px-4 from a component's host and px-2 from the template that uses it both set horiz...
Open Graph Description: Which @angular/* package(s) are relevant/related to the feature request? core Description Utility CSS frameworks make two different class names conflict: px-4 from a component's host and px-2 from ...
X Description: Which @angular/* package(s) are relevant/related to the feature request? core Description Utility CSS frameworks make two different class names conflict: px-4 from a component's host and px-2 f...
Opengraph URL: https://github.com/angular/angular/issues/72094
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"feat(core): let applications merge the classes of an element before they are written (provideClassMerge)","articleBody":"### Which @angular/* package(s) are relevant/related to the feature request?\n\ncore\n\n### Description\n\nUtility CSS frameworks make two *different* class names conflict: `px-4` from a component's host and `px-2` from the template that uses it both set horizontal padding. Angular applies both, and the winner is decided by the order of the rules in the stylesheet, not by where the classes come from. So a consumer can't reliably override a component's classes.\n\nThis is now a mainstream setup: `ng new` offers Tailwind CSS as a stylesheet system and `ng add tailwindcss` configures it. Component libraries built on it (spartan/ui, shadcn-style libraries) all need to resolve these conflicts, usually with `tailwind-merge`.\n\nIn other frameworks this is simple because a component receives `className` / `class` as a prop and composes it itself (`cn(own, props.className)`). In Angular the classes of a host element come from sources the component can't see: the consumer's `class` and `[class]` / `[class.x]` bindings, host directives, other directives and `Renderer2`. There is no single place to merge them, so libraries work around it after Angular has written the classes. spartan/ui, for example, does it with `effect`s, a `MutationObserver` per element and suppressing CSS transitions during hydration, because the classes land in two steps and cause flicker. That's ~950 lines (with tests) and a measurable runtime cost.\n\nAngular already knows every class source of an element and their precedence, so it's the natural place to resolve conflicts once, before writing to the DOM.\n\n### Proposed solution\n\nA small, generic, opt-in hook. It isn't Tailwind specific: any function that turns a list of classes into a class string.\n\n```ts\nimport {provideClassMerge} from '@angular/core';\nimport {twMerge} from 'tailwind-merge';\n\nbootstrapApplication(App, {\n providers: [provideClassMerge((classes) => twMerge(classes))],\n});\n```\n\nSemantics:\n\n- Angular passes the classes of an element in its precedence order, lowest first: host directives → component host → other directives (matching order) → template → `Renderer2.addClass`. Within a source: static `class` → `[class]` → `[class.x]` (in template order).\n- The merge function is called once per change and the result is written to `class` with a single write.\n- SSR and hydration (including incremental hydration) produce the same classes on the server and the client. Server-rendered classes Angular doesn't own are kept until the app is stable, so classes such as `RouterLinkActive`'s don't flicker.\n- Classes added with `Renderer2.addClass` (`RouterLinkActive`, `NgClass`) take part in the merge, and `removeClass` restores the class they replaced. Classes added outside Angular (`classList`, `animate.enter`) are kept as they are.\n- Tree-shakable: without the provider only an injection token lands in the bundle. `[style]` bindings are untouched.\n- The function must be pure and deterministic (results are cached per template location).\n\n### Prototype and numbers\n\nI have a working implementation with tests (acceptance, browser, platform-server hydration, forms), API docs and a guide section: [diff against v21.2.16](https://github.com/angular/angular/compare/v21.2.16...trs-dev-1:angular:prototype/class-merge-hook) (branch `prototype/class-merge-hook` on my fork; I'll rebase it on `main` for a PR). The existing suites pass unchanged. With a global identity merge, the only differences are class order in 8 specs that assert `className` strings.\n\nTo validate it, spartan/ui (300 components) was migrated from its userland solution to the hook. Measured on the spartan docs app (Chromium, 4x CPU throttling, median of 7 runs):\n\n| | Userland merging (today) | `provideClassMerge` |\n| --- | --- | --- |\n| Elements with different classes (~46k elements, SSR + hydrated) | – | **0** |\n| Script time, `/components/date-picker` | 1637 ms | **531 ms** |\n| Total blocking time, `/components/date-picker` | 2982 ms | **1844 ms** |\n| Transition flicker on load without suppression (98 routes) | 152 transitions | **0 caused by classes** |\n| SSR time per route | 171 ms | 172 ms |\n\nCompared to stock Angular without any merging, on a list of helm-like components: rendering is faster (one `class` write per element instead of one `classList.add` per class), and updates are on par (1k rows: render 57.3 → 49.2 ms, update 13.2 → 12.4 ms).\n\nKnown cost: each changed class binding re-merges the element, so an element with N changed bindings is merged N times in one change detection.\n\n### Alternatives considered\n\n- **Userland, after Angular writes the classes** (what libraries do today): needs effects and DOM observation on every element, writes classes twice, and causes transitions during hydration that have to be suppressed.\n- **A single `[class]` binding owned by the component** (`hostClass = computed(() => cn(base, consumerClass()))` with a `class` input): it misses classes from other directives, host directives and `Renderer2`, and takes `class` away from consumers as a normal attribute.\n- **A compiler-level solution**: the sources are only known at runtime (applied directives, `createComponent({directives})`, `Renderer2`, hydration), so a runtime hook is needed anyway.\n\nI'd be happy to open a PR if the direction looks good to the team.\n\ncc spartan/ui maintainers: @goetzrobin @ashley-hunter @MerlinMoos\n","author":{"url":"https://github.com/trs-dev-1","@type":"Person","name":"trs-dev-1"},"datePublished":"2026-11-18T21:39:49Z","url":"https://github.com/angular/angular/issues/72094"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:d48ae18c-029a-6f07-46c3-3c721561bcd1 |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | AA6E:2270F4:101FAB8:15764F2:6B0110A9 |
| html-safe-nonce | ffc0731fdcef7e5bd2d8769cf464119bf78101a1206c04d4576355ca23f72d6b |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJBQTZFOjIyNzBGNDoxMDFGQUI4OjE1NzY0RjI6NkIwMTEwQTkiLCJ2aXNpdG9yX2lkIjoiMzcyMzgyOTk2NDE4MTY3MjEwNSIsInJlZ2lvbl9lZGdlIjoiaWFkIiwicmVnaW9uX3JlbmRlciI6ImlhZCJ9 |
| visitor-hmac | 58aa7094531647782167c6b1c02d0e3d712f62e31002c250c9f42c6773e58467 |
| hovercard-subject-tag | issue:6477271157 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/angular/angular/72094/issue_layout |
| twitter:image | https://opengraph.githubassets.com/e5f32a01a19377eacd94b05da1afc62e7b501c6c0c0737e344ea914f3b21b79f/angular/angular/issues/72094 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/e5f32a01a19377eacd94b05da1afc62e7b501c6c0c0737e344ea914f3b21b79f/angular/angular/issues/72094 |
| og:image:alt | Which @angular/* package(s) are relevant/related to the feature request? core Description Utility CSS frameworks make two different class names conflict: px-4 from a component's host and px-2 from ... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | trs-dev-1 |
| hostname | github.com |
| expected-hostname | github.com |
| None | cb7fa109eca7d4156c889f474306b0e91336055e9adf8fd4684b61e49094d124 |
| turbo-cache-control | no-preview |
| go-import | github.com/angular/angular git https://github.com/angular/angular.git |
| octolytics-dimension-user_id | 139426 |
| octolytics-dimension-user_login | angular |
| octolytics-dimension-repository_id | 24195339 |
| octolytics-dimension-repository_nwo | angular/angular |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 24195339 |
| octolytics-dimension-repository_network_root_nwo | angular/angular |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 2b59d31a4e44f08b7af67a4b67f8fd0af3befe2a |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width