angular · dgp1130 · Feb 26, 2026 · Feb 26, 2026
diff --git a/goldens/public-api/platform-browser/index.api.md b/goldens/public-api/platform-browser/index.api.md
@@ -54,6 +54,15 @@ export class By {
 // @public
 export function createApplication(options?: ApplicationConfig, context?: BootstrapContext): Promise<ApplicationRef>;
 
+// @public
+export class CssVarNamespacer {
+    namespace(name: string): string;
+    // (undocumented)
+    static ɵfac: i0.ɵɵFactoryDeclaration<CssVarNamespacer, never>;
+    // (undocumented)
+    static ɵprov: i0.ɵɵInjectableDeclaration<CssVarNamespacer>;
+}
+
 // @public
 export function disableDebugTools(): void;
 
@@ -198,6 +207,9 @@ export const platformBrowser: (extraProviders?: StaticProvider[]) => PlatformRef
 // @public
 export function provideClientHydration(...features: HydrationFeature<HydrationFeatureKind>[]): EnvironmentProviders;
 
+// @public
+export function provideCssVarNamespacing(namespace: string): EnvironmentProviders;
+
 // @public
 export function provideProtractorTestingSupport(): Provider[];
 

diff --git a/.../compliance/test_cases/r3_view_compiler_styling/component_styles/encapsulation_default.js b/.../compliance/test_cases/r3_view_compiler_styling/component_styles/encapsulation_default.js
diff --git a/packages/compiler/src/render3/view/compiler.ts b/packages/compiler/src/render3/view/compiler.ts
@@ -11,7 +11,7 @@ import * as core from '../../core';
 import {CssSelector} from '../../directive_matching';
 import * as o from '../../output/output_ast';
 import {ParseError, ParseSourceSpan} from '../../parse_util';
-import {ShadowCss} from '../../shadow_css';
+import {namespaceCssVariables, ShadowCss} from '../../shadow_css';
 import {CompilationJobKind, TemplateCompilationMode} from '../../template/pipeline/src/compilation';
 import {emitHostBindingFunction, emitTemplateFn, transform} from '../../template/pipeline/src/emit';
 import {ingestComponent, ingestHostBinding} from '../../template/pipeline/src/ingest';
@@ -300,10 +300,11 @@ export function compileComponentFromMetadata(
   let hasStyles = !!meta.externalStyles?.length;
   // e.g. `styles: [str1, str2]`
   if (meta.styles && meta.styles.length) {
+    const namespacedStyles = meta.styles.map((s) => namespaceCssVariables(s));
     const styleValues =
       meta.encapsulation == core.ViewEncapsulation.Emulated
-        ? compileStyles(meta.styles, CONTENT_ATTR, HOST_ATTR)
-        : meta.styles;
+        ? compileStyles(namespacedStyles, CONTENT_ATTR, HOST_ATTR)
+        : namespacedStyles;
     const styleNodes = styleValues.reduce((result, style) => {
       if (style.trim().length > 0) {
         result.push(constantPool.getConstLiteral(o.literal(style)));

diff --git a/packages/compiler/src/shadow_css.ts b/packages/compiler/src/shadow_css.ts
@@ -1130,13 +1130,36 @@ const _cssCommaInPlaceholderReGlobal = new RegExp(COMMA_IN_PLACEHOLDER, 'g');
 const _cssSemiInPlaceholderReGlobal = new RegExp(SEMI_IN_PLACEHOLDER, 'g');
 const _cssColonInPlaceholderReGlobal = new RegExp(COLON_IN_PLACEHOLDER, 'g');
 
+// Matches `/* DISABLE_NAMESPACING */` optionally followed by any characters
+// that are not a semicolon or closing brace (e.g. whitespace or a property name),
+// up until it hits a CSS variable `--some-name`.
+const _cssNamespaceRe = new RegExp(
+  String.raw`(?:(/\*\s*DISABLE_NAMESPACING\s*\*/)[^;{}]*?)?(--[a-zA-Z0-9_-]+)`,
+  'g',
+);
+
 export class CssRule {
   constructor(
     public selector: string,
     public content: string,
   ) {}
 }
 
+/**
+ * Transforms CSS variables within a stylesheet to include a namespace placeholder.
+ *
+ * E.g. `--foo: bar;` becomes `--%NS%foo: bar;`
+ * E.g. `color: var(--foo);` becomes `color: var(--%NS%foo);`
+ *
+ * If a declaration or usage is preceded by `/* DISABLE_NAMESPACING *\/`, it is NOT transformed.
+ */
+export function namespaceCssVariables(cssText: string): string {
+  return cssText.replace(_cssNamespaceRe, (match, disableComment, varName) => {
+    if (disableComment) return match;
+    return `--%NS%${varName.substring('--'.length)}`;
+  });
+}
+
 export function processRules(input: string, ruleCallback: (rule: CssRule) => CssRule): string {
   const escaped = escapeInStrings(input);
   const inputWithEscapedBlocks = escapeBlocks(escaped, CONTENT_PAIRS, BLOCK_PLACEHOLDER);

diff --git a/packages/compiler/test/shadow_css/shadow_css_spec.ts b/packages/compiler/test/shadow_css/shadow_css_spec.ts
@@ -6,6 +6,7 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
+import {namespaceCssVariables} from '../../src/shadow_css';
 import {shim} from './utils';
 
 describe('ShadowCss', () => {
@@ -397,4 +398,91 @@ describe('ShadowCss', () => {
       );
     });
   });
+
+  describe('CSS variable namespacing', () => {
+    it('should inject `%NS%` placeholder into CSS variable declarations and usages', () => {
+      const input = `
+.foo {
+  --my-color: red;
+  color: var(--my-color, blue);
+}
+      `.trim();
+
+      const expected = `
+.foo {
+  --%NS%my-color: red;
+  color: var(--%NS%my-color, blue);
+}
+      `.trim();
+
+      expect(namespaceCssVariables(input)).toEqualCss(expected);
+    });
+
+    it('should not inject `%NS%` when `/* DISABLE_NAMESPACING */` comment is present', () => {
+      const input = `
+.foo {
+  /* DISABLE_NAMESPACING */
+  --my-color: green;
+  background: var(
+    /* DISABLE_NAMESPACING */
+    --my-color
+  );
+}
+      `.trim();
+
+      const expected = `
+.foo {
+  /* DISABLE_NAMESPACING */
+  --my-color: green;
+  background: var(
+    /* DISABLE_NAMESPACING */
+    --my-color
+  );
+}
+      `.trim();
+
+      expect(namespaceCssVariables(input)).toEqualCss(expected);
+    });
+    it('should not inject `%NS%` when `/* DISABLE_NAMESPACING */` comment is present on the property declaration', () => {
+      const input = `
+.foo {
+  /* DISABLE_NAMESPACING */
+  color: var(--my-color, blue);
+}
+      `.trim();
+
+      const expected = `
+.foo {
+  /* DISABLE_NAMESPACING */
+  color: var(--my-color, blue);
+}
+      `.trim();
+
+      expect(namespaceCssVariables(input)).toEqualCss(expected);
+    });
+
+    it('should correctly handle multiple `var()` functions with isolated `/* DISABLE_NAMESPACING */` comments', () => {
+      const input = `
+.foo {
+  border: var(/* DISABLE_NAMESPACING */ --border-size) solid var(--border-color);
+  box-shadow: 
+    var(--shadow-1),
+    var(/* DISABLE_NAMESPACING */ --shadow-2),
+    var(--shadow-3);
+}
+      `.trim();
+
+      const expected = `
+.foo {
+  border: var(/* DISABLE_NAMESPACING */ --border-size) solid var(--%NS%border-color);
+  box-shadow: 
+    var(--%NS%shadow-1),
+    var(/* DISABLE_NAMESPACING */ --shadow-2),
+    var(--%NS%shadow-3);
+}
+      `.trim();
+
+      expect(namespaceCssVariables(input)).toEqualCss(expected);
+    });
+  });
 });
diff --git a/packages/core/test/acceptance/csp_spec.ts b/packages/core/test/acceptance/csp_spec.ts
@@ -30,7 +30,7 @@ describe('CSP integration', () => {
     for (let i = 0; i < styles.length; i++) {
       const style = styles[i];
       const nonce = style.getAttribute('nonce');
-      if (nonce && style.textContent?.includes('--csp-test-var')) {
+      if (nonce && style.textContent?.includes('csp-test-var')) {
         nonces.push(nonce);
       }
     }

diff --git a/packages/core/test/bundling/animations-standalone/bundle.golden_symbols.json b/packages/core/test/bundling/animations-standalone/bundle.golden_symbols.json
@@ -55,6 +55,7 @@
       "CONTENT_ATTR",
       "CONTEXT",
       "CSP_NONCE",
+      "CSS_VAR_NAMESPACE",
       "ChainedInjector",
       "ChangeDetectionScheduler",
       "ChangeDetectionSchedulerImpl",

diff --git a/packages/core/test/bundling/create_component/bundle.golden_symbols.json b/packages/core/test/bundling/create_component/bundle.golden_symbols.json
@@ -32,6 +32,7 @@
       "CONTENT_ATTR",
       "CONTEXT",
       "CSP_NONCE",
+      "CSS_VAR_NAMESPACE",
       "ChainedInjector",
       "ChangeDetectionScheduler",
       "ChangeDetectionSchedulerImpl",

diff --git a/packages/core/test/bundling/defer/bundle.golden_symbols.json b/packages/core/test/bundling/defer/bundle.golden_symbols.json
@@ -14,6 +14,7 @@
       "COMPONENT_REGEX",
       "COMPONENT_VARIABLE",
       "CONTENT_ATTR",
+      "CSS_VAR_NAMESPACE",
       "DefaultDomRenderer2",
       "DomAdapter",
       "DomEventsPlugin",

diff --git a/packages/core/test/bundling/forms_reactive/bundle.golden_symbols.json b/packages/core/test/bundling/forms_reactive/bundle.golden_symbols.json
@@ -48,6 +48,7 @@
       "CONTENT_ATTR",
       "CONTEXT",
       "CSP_NONCE",
+      "CSS_VAR_NAMESPACE",
       "ChainedInjector",
       "ChangeDetectionScheduler",
       "ChangeDetectionSchedulerImpl",

diff --git a/packages/core/test/bundling/forms_template_driven/bundle.golden_symbols.json b/packages/core/test/bundling/forms_template_driven/bundle.golden_symbols.json
@@ -48,6 +48,7 @@
       "CONTENT_ATTR",
       "CONTEXT",
       "CSP_NONCE",
+      "CSS_VAR_NAMESPACE",
       "ChainedInjector",
       "ChangeDetectionScheduler",
       "ChangeDetectionSchedulerImpl",

diff --git a/packages/core/test/bundling/hydration/bundle.golden_symbols.json b/packages/core/test/bundling/hydration/bundle.golden_symbols.json
@@ -40,6 +40,7 @@
       "CONTENT_ATTR",
       "CONTEXT",
       "CSP_NONCE",
+      "CSS_VAR_NAMESPACE",
       "ChainedInjector",
       "ChangeDetectionScheduler",
       "ChangeDetectionSchedulerImpl",

diff --git a/packages/core/test/bundling/router/bundle.golden_symbols.json b/packages/core/test/bundling/router/bundle.golden_symbols.json
@@ -48,6 +48,7 @@
       "CONTEXT",
       "CREATE_VIEW_TRANSITION",
       "CSP_NONCE",
+      "CSS_VAR_NAMESPACE",
       "CanActivate",
       "CanDeactivate",
       "ChainedInjector",

diff --git a/packages/core/test/bundling/standalone_bootstrap/bundle.golden_symbols.json b/packages/core/test/bundling/standalone_bootstrap/bundle.golden_symbols.json
@@ -32,6 +32,7 @@
       "CONTENT_ATTR",
       "CONTEXT",
       "CSP_NONCE",
+      "CSS_VAR_NAMESPACE",
       "ChainedInjector",
       "ChangeDetectionScheduler",
       "ChangeDetectionSchedulerImpl",

diff --git a/packages/platform-browser/src/dom/css_var_namespacer.ts b/packages/platform-browser/src/dom/css_var_namespacer.ts
@@ -0,0 +1,47 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import {inject, Injectable} from '@angular/core';
+import {CSS_VAR_NAMESPACE} from './dom_renderer';
+
+/**
+ * A service that can be used to manually namespace CSS variable names at runtime.
+ * This is useful when reading or setting CSS variables dynamically in JavaScript that
+ * were transformed by the compiler during the build.
+ *
+ * @publicApi
+ */
+@Injectable({providedIn: 'root'})
+export class CssVarNamespacer {
+  private readonly namespacePrefix = inject(CSS_VAR_NAMESPACE, {optional: true}) ?? '';
+
+  /**
+   * Prepends the namespace prefix to a CSS variable name.
+   *
+   * @param name The CSS variable name to namespace, including the leading `--`.
+   * @returns The namespaced CSS variable name, including the leading `--`. Returns the input
+   *     unchanged if no namespace is configured.
+   */
+  namespace(name: string): string {
+    // Validate that the whole `--foo` variable is passed in.
+    if (typeof ngDevMode === 'undefined' || ngDevMode) {
+      if (!name.startsWith('--')) {
+        throw new Error(
+          `CSS variable names passed to \`CssVarNamespacer\` must start with '--', got: '${name}'`,
+        );
+      }
+    }
+
+    // We want to support libraries which might be used by applications which do and don't
+    // namespace variables. Therefore the library always needs to use `CssVarNamespacer`, even
+    // though the application may not actually be namespacing anything.
+    if (!this.namespacePrefix) return name;
+
+    return `--${this.namespacePrefix}${name.substring('--'.length)}`;
+  }
+}