CSS Variable Namespacing by mattrbeck · Pull Request #68846 · angular/angular

mattrbeck · 2026-05-20T23:47:41Z

Superseds #67362. Primary differences are:

Opt-out syntax is now a --global prefix, e.g. --global--foo: blue
Added support for style properties, e.g. [style.--foo]="'blue'"
Added errors for prefix missing trailing double-hyphen, e.g. --global-foo

This adds CSS variable namespacing support to Angular.

This allows multiple apps to coexist on the same page with isolated CSS variables, meaning one can use color: var(--primary-color); without worrying about accidentally inheriting the primary color of a different app which happens to set it on an ancestor element.

To enable this feature, call provideCssVarNamespacing in your app.config.ts. Typically you want to configure this with the same value as APP_ID, but with an additional separator at the end (a - or _):

import {ApplicationConfig, APP_ID} from '@angular/core';
import {provideCssVarNamespacing} from '@angular/platform-browser';

export const appConfig: ApplicationConfig = {
  providers: [
    {
      provide: APP_ID,
      useValue: 'my-app',
    },
    provideCssVarNamespacing('my-app_'),
  ],
};

This only namespaces styles in Angular components (the styles or styleUrls properties in @Component). It does not namespace global styles, which are out of scope for this effort.

Namespacing does naturally break any JavaScript references to CSS variables, therefore this PR also introduces CssVarNamespacer which allows you to automatically namespace variables based on what is configured in the application.

import {CssVarNamespacer} from '@angular/platform-browser';

const namespacer = inject(CssVarNamespacer);
const color = namespacer.namespace('--primary-color');
getComputedStyle(someElement).getPropertyValue(color);

Libraries should consider always using the namespacer when referring to CSS variables, as they may be consumed by applications which enable namespacing.

Namespacing works by having the compiler unconditionally prepend %NS% to CSS variables (--foo -> --%NS%foo) and then at runtime replaces %NS% with a namespace specified by provideCssVarNamespacing('my-app_') (--%NS%foo -> --my-app_foo).

Internal bug: b/485672083

Closes #67362 via supersession.

mattrbeck · 2026-05-21T03:30:03Z

+ *     followed by a separator, such as 'my-app_'.
+ * @publicApi
+ */
+export function provideCssVarNamespacing(namespace: string): EnvironmentProviders {


Question for reviewer: I'm inclined to automatically add a _ suffic to the provided namespace if it's non-empty and doesn't terminate with a - or _. Any opinions? Might be nice to automatically add the separator.

I don't feel too strongly, since this should be mostly unobservable by the application.

I wonder if it might be better to be consistent (either always add the suffix or never do) just to reduce unintuitive effects and also reduce bundle size (drop an otherwise unnecessary if statement).

mattrbeck · 2026-05-21T03:31:33Z

+    @Inject(CSS_VAR_NAMESPACE) @Optional() cssVarNamespace: string | null = null,
  ) {
-    this.defaultRenderer = new DefaultDomRenderer2(eventManager, doc, ngZone, this.tracingService);
+    this.cssVarNamespace = cssVarNamespace ?? '';


Question for reviewer: Rather than falling back to an empty string, I'm inclined to default to the APP_ID. If a user wants to disable prefixing app-wide, they could still provideCssVarNamespacing(''). Thoughts?

We still need CSS namespacing to be off-by-default right, otherwise this would be a breaking change? So I would think if CSS_VAR_NAMESPACE is not provided, it needs to default to '' just to not break existing apps.

Now we could have provideCssVarNamespacing() (with no argument) default to APP_ID as the namespace. I don't have any objection to that.

SkyZeroZx · 2026-05-21T03:57:15Z

+    // Validate that the whole `--foo` variable is passed in.
+    if (typeof ngDevMode === 'undefined' || ngDevMode) {
+      if (!name.startsWith('--')) {
+        throw new Error(


I think this should be a RuntimeError ?

SkyZeroZx · 2026-05-21T04:00:05Z

+ *
+ * Typically set via {@link provideCssVarNamespacing}.
+ */
+export const CSS_VAR_NAMESPACE = new InjectionToken<string>('CSS_VAR_NAMESPACE');


We can save a few bytes by doing

Suggested change

export const CSS_VAR_NAMESPACE = new InjectionToken<string>('CSS_VAR_NAMESPACE');

export const CSS_VAR_NAMESPACE = new InjectionToken<string>(typeof ngDevMode !== 'undefined' && ngDevMode ? 'CSS_VAR_NAMESPACE' : '');

Other suggestion, what if that token had a default factory ?
This was we would skip that optional: true part everywhere it is injected

Adds logic to inject symbols into CSS variables for runtime namespacing. The runtime now replaces instances of `%NS%` with a namespacing variable, limiting reach of CSS variables to the current app. An opt-out syntax of a `--global` prefix allows users to avoid this behavior.

Using `--global-foo` is now prohibited. We suspect these cases will likely be typos of `--global--foo` in the future, so we blanket ban them and direct users to the expected syntax.

Adds support for namespacing css variables in style properties. Behaves as you'd expect following the implementation for stylesheets generally. This change also moves the error message into a util function since we now need to produce the same error in three places.

dgp1130

Looks great, no major concerns on my end. Thanks for taking this on @mattrbeck!

dgp1130 · 2026-05-22T00:43:55Z

+    if (!leadingVar && !trailingColon) {
+      return match;
+    }


Question: I assume the need for the leading var or trailing colon is to avoid namespacing situations like .foo--bar {}? Might be worth a comment to call that out more explicitly here.

dgp1130 · 2026-05-22T00:44:08Z

+      result = `--%NS%${varName.substring('--'.length)}`;
+    }
+
+    return (leadingVar || '') + result + (trailingColon || '');


Nit: Prefer ??.

dgp1130 · 2026-05-22T00:46:50Z

Good catch on these edge cases, could definitely seem some of them being problematic if we didn't cover them!

dgp1130 · 2026-05-22T00:52:17Z

+ *     followed by a separator, such as 'my-app_'.
+ * @publicApi
+ */
+export function provideCssVarNamespacing(namespace: string): EnvironmentProviders {


I don't feel too strongly, since this should be mostly unobservable by the application.

I wonder if it might be better to be consistent (either always add the suffix or never do) just to reduce unintuitive effects and also reduce bundle size (drop an otherwise unnecessary if statement).

dgp1130 · 2026-05-22T00:56:55Z

+    @Inject(CSS_VAR_NAMESPACE) @Optional() cssVarNamespace: string | null = null,
  ) {
-    this.defaultRenderer = new DefaultDomRenderer2(eventManager, doc, ngZone, this.tracingService);
+    this.cssVarNamespace = cssVarNamespace ?? '';


We still need CSS namespacing to be off-by-default right, otherwise this would be a breaking change? So I would think if CSS_VAR_NAMESPACE is not provided, it needs to default to '' just to not break existing apps.

Now we could have provideCssVarNamespacing() (with no argument) default to APP_ID as the namespace. I don't have any objection to that.

dgp1130 · 2026-05-22T00:59:54Z

      return match;
    }

+    if (varName.startsWith('--global-') && !varName.startsWith('--global--')) {


Question: We're assuming there are no/few legitimate use cases of --global-foo as an unrelated variable name right?

dgp1130 · 2026-05-22T01:03:37Z

+          if (boundName.startsWith('--global-') && !boundName.startsWith('--global--')) {
+            this._reportError(getInvalidCssGlobalError(boundName), boundProp.sourceSpan);
+          }
+          if (boundName.startsWith('--global--')) {
+            boundPropertyName = '--' + boundName.substring('--global--'.length);
+          } else {
+            boundPropertyName = '--%NS%' + boundName.substring('--'.length);
+          }


Consider: Is it possible to factor this whole piece of logic into a shared function? I'm a bit worried this could easily diverge if we forget one of them exists.

dgp1130 · 2026-05-22T01:06:50Z

+    if (style.startsWith('--')) {
+      style = style.replace('%NS%', this.cssVarNamespace);
+      el.style.setProperty(style, value, flags & RendererStyleFlags2.Important ? 'important' : '');
+    } else if (flags & (RendererStyleFlags2.DashCase | RendererStyleFlags2.Important)) {


Consider: We can reduce duplication of setProperty by separating the if statements. Same for removeStyle.

Suggested change

} else if (flags & (RendererStyleFlags2.DashCase | RendererStyleFlags2.Important)) {

if (style.startsWith('--')) {

style = style.replace('%NS%', this.cssVarNamespace);

}

if (flags & (RendererStyleFlags2.DashCase | RendererStyleFlags2.Important)) {

pullapprove Bot requested review from crisbeto and kirjs May 20, 2026 23:47

angular-robot Bot added the detected: feature PR contains a feature commit label May 20, 2026

mattrbeck added core: stylesheets core: CSS encapsulation compiler: styles labels May 20, 2026

mattrbeck force-pushed the css_var_namespacing branch from 6c27311 to 302644d Compare May 21, 2026 00:01

angular-robot Bot added the area: compiler Issues related to `ngc`, Angular's template compiler label May 21, 2026

ngbot Bot added this to the Backlog milestone May 21, 2026

mattrbeck requested review from dgp1130 and removed request for kirjs May 21, 2026 00:02

pullapprove Bot requested a review from atscott May 21, 2026 00:03

mattrbeck force-pushed the css_var_namespacing branch from 302644d to e95f942 Compare May 21, 2026 00:22

mattrbeck commented May 21, 2026

View reviewed changes

SkyZeroZx reviewed May 21, 2026

View reviewed changes

Comment thread packages/platform-browser/src/dom/css_var_namespacer.ts Outdated

SkyZeroZx reviewed May 21, 2026

View reviewed changes

JeanMeche reviewed May 21, 2026

View reviewed changes

Comment thread packages/platform-browser/src/dom/css_var_namespacer.ts Outdated

mattrbeck added 3 commits May 21, 2026 17:24

feat(compiler): Add an error for --global-foo cases

9e43b00

Using `--global-foo` is now prohibited. We suspect these cases will likely be typos of `--global--foo` in the future, so we blanket ban them and direct users to the expected syntax.

mattrbeck force-pushed the css_var_namespacing branch from e95f942 to 5dd7961 Compare May 22, 2026 00:24

dgp1130 mentioned this pull request May 22, 2026

CSS Variable Namespacing #67362

Closed

mattrbeck added area: core Issues related to the framework runtime target: minor This PR is targeted for the next minor release labels May 22, 2026

dgp1130 approved these changes May 22, 2026

View reviewed changes

	export const CSS_VAR_NAMESPACE = new InjectionToken<string>('CSS_VAR_NAMESPACE');
	export const CSS_VAR_NAMESPACE = new InjectionToken<string>(typeof ngDevMode !== 'undefined' && ngDevMode ? 'CSS_VAR_NAMESPACE' : '');

Conversation

mattrbeck commented May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SkyZeroZx May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

dgp1130 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

mattrbeck commented May 20, 2026 •

edited

Loading

SkyZeroZx May 21, 2026 •

edited

Loading