feat(platform-browser): Add IsolatedShadowDom encapsulation method (#62723)

ryan-bendel · crisbeto · commit d24d5742db69 · 2025-08-06T16:48:37.000+02:00
IsolatedShadowDom encapsulation fixes style leakage in Shadowdom encapsulation by removing sharedstyleshost from dom-renderer IsolatedShadowdom class. Updates docs. PR Close #62723
diff --git a/adev/shared-docs/pipeline/api-gen/rendering/test/fake-cli-entries.json b/adev/shared-docs/pipeline/api-gen/rendering/test/fake-cli-entries.json
@@ -177,7 +177,8 @@
           "enum": [
             "Emulated",
             "None",
-            "ShadowDom"
+            "ShadowDom",
+            "IsolatedShadowDom"
           ],
           "description": "The view encapsulation strategy to use in the new application."
         }
@@ -367,7 +368,8 @@
           "enum": [
             "Emulated",
             "None",
-            "ShadowDom"
+            "ShadowDom",
+            "IsolatedShadowDom"
           ],
           "description": "The view encapsulation strategy to use in the new component."
         }
diff --git a/adev/src/app/features/update/recommendations.ts b/adev/src/app/features/update/recommendations.ts
@@ -1032,7 +1032,7 @@ export const RECOMMENDATIONS: Step[] = [
     level: ApplicationComplexity.Advanced,
     step: 'viewencapsulation native removed',
     action:
-      'The component view encapsulation option `ViewEncapsulation.Native` has been removed. Use `ViewEncapsulation.ShadowDom` instead. `ng update` will migrate you automatically.',
+      'The component view encapsulation option `ViewEncapsulation.Native` has been removed. Use `ViewEncapsulation.ShadowDom` or `ViewEncapsulation.IsolatedShadowDom` instead. `ng update` will migrate you automatically.',
   },
   {
     possibleIn: 1100,
diff --git a/adev/src/content/ai/mcp-server-setup.md b/adev/src/content/ai/mcp-server-setup.md
@@ -90,4 +90,4 @@ This tool lists all the applications and libraries in your current Angular works
 
 ## Feedback and New Ideas
 
-The Angular team welcomes your feedback on the existing MCP capabilities and any ideas you have for new tools or features. Please share your thoughts by opening an issue on the [angular/angular GitHub repository](https://github.com/angular/angular/issues).
+The Angular team welcomes your feedback on the existing MCP capabilities and any ideas you have for new tools or features. Please share your thoughts by opening an issue on the [angular/angular GitHub repository](https://github.com/angular/angular/issues).
diff --git a/adev/src/content/cli/help/generate.json b/adev/src/content/cli/help/generate.json
@@ -998,4 +998,4 @@
       "deprecated": false
     }
   ]
-}
+}
diff --git a/adev/src/content/cli/help/new.json b/adev/src/content/cli/help/new.json
@@ -195,4 +195,4 @@
       "description": "Create an initial application that does not utilize `zone.js`."
     }
   ]
-}
+}
diff --git a/adev/src/content/guide/animations/complex-sequences.md b/adev/src/content/guide/animations/complex-sequences.md
@@ -121,11 +121,11 @@ IMPORTANT: If you need to animate the items of an `*ngFor` list and there is a p
 
 ## Animations and Component View Encapsulation
 
-Angular animations are based on the components DOM structure and do not directly take [View Encapsulation](guide/components/styling#style-scoping) into account, this means that components using `ViewEncapsulation.Emulated` behave exactly as if they were using `ViewEncapsulation.None` (`ViewEncapsulation.ShadowDom` behaves differently as we'll discuss shortly).
+Angular animations are based on the components DOM structure and do not directly take [View Encapsulation](guide/components/styling#style-scoping) into account, this means that components using `ViewEncapsulation.Emulated` behave exactly as if they were using `ViewEncapsulation.None` (`ViewEncapsulation.ShadowDom` and `ViewEncapsulation.IsolatedShadowDom` behave differently as we'll discuss shortly).
 
 For example if the `query()` function (which you'll see more of in the rest of the Animations guide) were to be applied at the top of a tree of components using the emulated view encapsulation, such query would be able to identify (and thus animate) DOM elements on any depth of the tree.
 
-On the other hand the `ViewEncapsulation.ShadowDom` changes the component's DOM structure by "hiding" DOM elements inside [`ShadowRoot`](https://developer.mozilla.org/docs/Web/API/ShadowRoot) elements. Such DOM manipulations do prevent some of the animations implementation to work properly since it relies on simple DOM structures and doesn't take `ShadowRoot` elements into account. Therefore it is advised to avoid applying animations to views incorporating components using the ShadowDom view encapsulation.
+On the other hand the `ViewEncapsulation.ShadowDom` and `ViewEncapsulation.IsolatedShadowDom` changes the component's DOM structure by "hiding" DOM elements inside [`ShadowRoot`](https://developer.mozilla.org/docs/Web/API/ShadowRoot) elements. Such DOM manipulations do prevent some of the animations implementation to work properly since it relies on simple DOM structures and doesn't take `ShadowRoot` elements into account. Therefore it is advised to avoid applying animations to views incorporating components using the ShadowDom view encapsulation.
 
 ## Animation sequence summary
 
@@ -141,4 +141,4 @@ You might also be interested in the following:
   <docs-pill href="guide/animations/transition-and-triggers" title="Transition and triggers"/>
   <docs-pill href="guide/animations/reusable-animations" title="Reusable animations"/>
   <docs-pill href="guide/routing/route-transition-animations" title="Route transition animations"/>
-</docs-pill-row>
+</docs-pill-row>
diff --git a/adev/src/content/guide/components/styling.md b/adev/src/content/guide/components/styling.md
@@ -36,7 +36,7 @@ and [stylus](https://stylus-lang.com).
 ## Style scoping
 
 Every component has a **view encapsulation** setting that determines how the framework scopes a
-component's styles. There are three view encapsulation modes: `Emulated`, `ShadowDom`, and `None`.
+component's styles. There are four view encapsulation modes: `Emulated`, `ShadowDom`, `IsolatedShadowDom`, and `None`.
 You can specify the mode in the `@Component` decorator:
 
 <docs-code language="angular-ts" highlight="[3]">
@@ -82,16 +82,20 @@ using [the web standard Shadow DOM API](https://developer.mozilla.org/docs/Web/W
 When enabling this mode, Angular attaches a shadow root to the component's host element and renders
 the component's template and styles into the corresponding shadow tree.
 
-This mode strictly guarantees that _only_ that component's styles apply to elements in the
-component's template. Global styles cannot affect elements in a shadow tree and styles inside the
-shadow tree cannot affect elements outside of that shadow tree.
+Styles inside the shadow tree cannot affect elements outside of that shadow tree.
 
 Enabling `ShadowDom` encapsulation, however, impacts more than style scoping. Rendering the
 component in a shadow tree affects event propagation, interaction
 with [the `<slot>` API](https://developer.mozilla.org/docs/Web/Web_Components/Using_templates_and_slots),
 and how browser developer tools show elements. Always understand the full implications of using
 Shadow DOM in your application before enabling this option.
 
+### ViewEncapsulation.IsolatedShadowDom
+
+Behaves as above, except this mode strictly guarantees that _only_ that component's styles apply to elements in the
+component's template. Global styles cannot affect elements in a shadow tree and styles inside the
+shadow tree cannot affect elements outside of that shadow tree.
+
 ### ViewEncapsulation.None
 
 This mode disables all style encapsulation for the component. Any styles associated with the
@@ -114,4 +118,4 @@ use [the `<link>` element](https://developer.mozilla.org/docs/Web/HTML/Element/l
 reference CSS files. Additionally, your CSS may
 use [the `@import`at-rule](https://developer.mozilla.org/docs/Web/CSS/@import) to reference
 CSS files. Angular treats these references as _external_ styles. External styles are not affected by
-emulated view encapsulation.
+emulated view encapsulation.
diff --git a/adev/src/content/reference/migrations/overview.md b/adev/src/content/reference/migrations/overview.md
@@ -30,4 +30,4 @@ Learn about how you can migrate your existing angular project to the latest feat
   <docs-card title="Self-closing tags" link="Migrate now" href="reference/migrations/self-closing-tags">
     Convert component templates to use self-closing tags where possible.
   </docs-card>
-</docs-card-container>
+</docs-card-container>
diff --git a/devtools/projects/ng-devtools/src/lib/devtools-tabs/directive-explorer/property-tab/component-metadata.component.ts b/devtools/projects/ng-devtools/src/lib/devtools-tabs/directive-explorer/property-tab/component-metadata.component.ts
@@ -36,7 +36,7 @@ export class ComponentMetadataComponent {
 
   private _nestedProps = inject(ElementPropertyResolver);
 
-  angularViewEncapsulationModes = ['Emulated', 'Native', 'None', 'ShadowDom'];
+  angularViewEncapsulationModes = ['Emulated', 'Native', 'None', 'ShadowDom', 'IsolatedShadowDom'];
   acxViewEncapsulationModes = ['Emulated', 'None'];
 
   readonly controller = computed(() => {
diff --git a/goldens/public-api/core/index.api.md b/goldens/public-api/core/index.api.md
@@ -2022,6 +2022,7 @@ export abstract class ViewContainerRef {
 // @public
 export enum ViewEncapsulation {
     Emulated = 0,
+    IsolatedShadowDom = 4,
     None = 2,
     ShadowDom = 3
 }
diff --git a/packages/compiler-cli/src/ngtsc/annotations/component/src/handler.ts b/packages/compiler-cli/src/ngtsc/annotations/component/src/handler.ts
@@ -862,7 +862,11 @@ export class ComponentDecoratorHandler
       }
     }
 
-    if (encapsulation === ViewEncapsulation.ShadowDom && metadata.selector !== null) {
+    if (
+      (encapsulation === ViewEncapsulation.ShadowDom ||
+        encapsulation === ViewEncapsulation.IsolatedShadowDom) &&
+      metadata.selector !== null
+    ) {
       const selectorError = checkCustomElementSelectorForErrors(metadata.selector);
       if (selectorError !== null) {
         if (diagnostics === undefined) {
diff --git a/packages/compiler/src/compiler_facade_interface.ts b/packages/compiler/src/compiler_facade_interface.ts
@@ -348,6 +348,7 @@ export enum ViewEncapsulation {
   // Historically the 1 value was for `Native` encapsulation which has been removed as of v11.
   None = 2,
   ShadowDom = 3,
+  IsolatedShadowDom = 4,
 }
 
 export type ChangeDetectionStrategy = number;
diff --git a/packages/compiler/src/core.ts b/packages/compiler/src/core.ts
@@ -23,6 +23,7 @@ export enum ViewEncapsulation {
   // Historically the 1 value was for `Native` encapsulation which has been removed as of v11.
   None = 2,
   ShadowDom = 3,
+  IsolatedShadowDom = 4,
 }
 
 export enum ChangeDetectionStrategy {
diff --git a/packages/core/src/compiler/compiler_facade_interface.ts b/packages/core/src/compiler/compiler_facade_interface.ts
@@ -348,6 +348,7 @@ export enum ViewEncapsulation {
   // Historically the 1 value was for `Native` encapsulation which has been removed as of v11.
   None = 2,
   ShadowDom = 3,
+  IsolatedShadowDom = 4,
 }
 
 export type ChangeDetectionStrategy = number;
diff --git a/packages/core/src/hydration/annotate.ts b/packages/core/src/hydration/annotate.ts
@@ -792,9 +792,12 @@ function conditionallyAnnotateNodePath(
  */
 function componentUsesShadowDomEncapsulation(lView: LView): boolean {
   const instance = lView[CONTEXT];
-  return instance?.constructor
-    ? getComponentDef(instance.constructor)?.encapsulation === ViewEncapsulation.ShadowDom
-    : false;
+  if (!instance?.constructor) return false;
+  const def = getComponentDef(instance.constructor);
+  return (
+    def?.encapsulation === ViewEncapsulation.ShadowDom ||
+    def?.encapsulation === ViewEncapsulation.IsolatedShadowDom
+  );
 }
 
 /**
diff --git a/packages/core/src/metadata/view.ts b/packages/core/src/metadata/view.ts
@@ -47,4 +47,10 @@ export enum ViewEncapsulation {
    * all the Component's styling.
    */
   ShadowDom = 3,
+  /**
+   * Similar to `ShadowDom`, but prevents any external styles from leaking into the
+   * component's ShadowRoot. This is useful when you want to ensure that the component's
+   * styles are completely isolated from the rest of the application, including global styles.
+   */
+  IsolatedShadowDom = 4,
 }
diff --git a/packages/core/src/render3/hmr.ts b/packages/core/src/render3/hmr.ts
@@ -245,7 +245,10 @@ function recreateLView(
     // shadow root. The browser will throw if we attempt to attach another one and there's no way
     // to detach it. Our only option is to make a clone only of the root node, replace the node
     // with the clone and use it for the newly-created LView.
-    if (oldDef.encapsulation === ViewEncapsulation.ShadowDom) {
+    if (
+      oldDef.encapsulation === ViewEncapsulation.ShadowDom ||
+      oldDef.encapsulation === ViewEncapsulation.IsolatedShadowDom
+    ) {
       const newHost = host.cloneNode(false) as HTMLElement;
       host.replaceWith(newHost);
       host = newHost;
diff --git a/packages/core/src/render3/instructions/shared.ts b/packages/core/src/render3/instructions/shared.ts
@@ -177,7 +177,10 @@ export function locateHostElement(
 
   // When using native Shadow DOM, do not clear host element to allow native slot
   // projection.
-  const preserveContent = preserveHostContent || encapsulation === ViewEncapsulation.ShadowDom;
+  const preserveContent =
+    preserveHostContent ||
+    encapsulation === ViewEncapsulation.ShadowDom ||
+    encapsulation === ViewEncapsulation.IsolatedShadowDom;
   const rootElement = renderer.selectRootElement(elementOrSelector, preserveContent);
   applyRootElementTransform(rootElement as HTMLElement);
   return rootElement;
diff --git a/packages/platform-browser/src/dom/dom_renderer.ts b/packages/platform-browser/src/dom/dom_renderer.ts
@@ -177,7 +177,8 @@ export class DomRendererFactory2 implements RendererFactory2, OnDestroy {
     if (
       typeof ngServerMode !== 'undefined' &&
       ngServerMode &&
-      type.encapsulation === ViewEncapsulation.ShadowDom
+      (type.encapsulation === ViewEncapsulation.ShadowDom ||
+        type.encapsulation === ViewEncapsulation.IsolatedShadowDom)
     ) {
       // Domino does not support shadow DOM.
       type = {...type, encapsulation: ViewEncapsulation.Emulated};
@@ -228,7 +229,20 @@ export class DomRendererFactory2 implements RendererFactory2, OnDestroy {
         case ViewEncapsulation.ShadowDom:
           return new ShadowDomRenderer(
             eventManager,
+            element,
+            type,
+            doc,
+            ngZone,
+            this.nonce,
+            platformIsServer,
+            tracingService,
+            this.registry,
+            this.maxAnimationTimeout,
             sharedStylesHost,
+          );
+        case ViewEncapsulation.IsolatedShadowDom:
+          return new ShadowDomRenderer(
+            eventManager,
             element,
             type,
             doc,
@@ -239,6 +253,7 @@ export class DomRendererFactory2 implements RendererFactory2, OnDestroy {
             this.registry,
             this.maxAnimationTimeout,
           );
+
         default:
           renderer = new NoneEncapsulationDomRenderer(
             eventManager,
@@ -501,6 +516,7 @@ class DefaultDomRenderer2 implements Renderer2 {
 }
 
 const AT_CHARCODE = (() => '@'.charCodeAt(0))();
+
 function checkNoSyntheticProp(name: string, nameKind: string) {
   if (name.charCodeAt(0) === AT_CHARCODE) {
     throw new RuntimeError(
@@ -521,7 +537,6 @@ class ShadowDomRenderer extends DefaultDomRenderer2 {
 
   constructor(
     eventManager: EventManager,
-    private sharedStylesHost: SharedStylesHost,
     private hostEl: any,
     component: RendererType2,
     doc: Document,
@@ -531,6 +546,7 @@ class ShadowDomRenderer extends DefaultDomRenderer2 {
     tracingService: TracingService<TracingSnapshot> | null,
     registry: AnimationRemovalRegistry,
     maxAnimationTimeout: number,
+    private sharedStylesHost?: SharedStylesHost,
   ) {
     super(
       eventManager,
@@ -542,7 +558,12 @@ class ShadowDomRenderer extends DefaultDomRenderer2 {
       maxAnimationTimeout,
     );
     this.shadowRoot = (hostEl as any).attachShadow({mode: 'open'});
-    this.sharedStylesHost.addHost(this.shadowRoot);
+
+    // SharedStylesHost is used to add styles to the shadow root by ShadowDom.
+    // This is optional as it is not used by IsolatedShadowDom.
+    if (this.sharedStylesHost) {
+      this.sharedStylesHost.addHost(this.shadowRoot);
+    }
     let styles = component.styles;
     if (ngDevMode) {
       // We only do this in development, as for production users should not add CSS sourcemaps to components.
@@ -588,18 +609,23 @@ class ShadowDomRenderer extends DefaultDomRenderer2 {
   override appendChild(parent: any, newChild: any): void {
     return super.appendChild(this.nodeOrShadowRoot(parent), newChild);
   }
+
   override insertBefore(parent: any, newChild: any, refChild: any): void {
     return super.insertBefore(this.nodeOrShadowRoot(parent), newChild, refChild);
   }
+
   override removeChild(_parent: any, oldChild: any): void {
     return super.removeChild(null, oldChild);
   }
+
   override parentNode(node: any): any {
     return this.nodeOrShadowRoot(super.parentNode(this.nodeOrShadowRoot(node)));
   }
 
   override destroy() {
-    this.sharedStylesHost.removeHost(this.shadowRoot);
+    if (this.sharedStylesHost) {
+      this.sharedStylesHost.removeHost(this.shadowRoot);
+    }
   }
 }
 
diff --git a/packages/platform-browser/test/dom/dom_renderer_spec.ts b/packages/platform-browser/test/dom/dom_renderer_spec.ts

Original file line number	Diff line number	Diff line change
`@@ -1032,7 +1032,7 @@ export const RECOMMENDATIONS: Step[] = [`
`1032`	`1032`	`level: ApplicationComplexity.Advanced,`
`1033`	`1033`	`step: 'viewencapsulation native removed',`
`1034`	`1034`	`action:`
`1035`		- 'The component view encapsulation option `ViewEncapsulation.Native` has been removed. Use `ViewEncapsulation.ShadowDom` instead. `ng update` will migrate you automatically.',
	`1035`	+ 'The component view encapsulation option `ViewEncapsulation.Native` has been removed. Use `ViewEncapsulation.ShadowDom` or `ViewEncapsulation.IsolatedShadowDom` instead. `ng update` will migrate you automatically.',
`1036`	`1036`	`},`
`1037`	`1037`	`{`
`1038`	`1038`	`possibleIn: 1100,`
Original file line number	Diff line number	Diff line change
`@@ -90,4 +90,4 @@ This tool lists all the applications and libraries in your current Angular works`
`90`	`90`
`91`	`91`	`## Feedback and New Ideas`
`92`	`92`
`93`		`-The Angular team welcomes your feedback on the existing MCP capabilities and any ideas you have for new tools or features. Please share your thoughts by opening an issue on the [angular/angular GitHub repository](https://github.com/angular/angular/issues).`
	`93`	`+The Angular team welcomes your feedback on the existing MCP capabilities and any ideas you have for new tools or features. Please share your thoughts by opening an issue on the [angular/angular GitHub repository](https://github.com/angular/angular/issues).`
Original file line number	Diff line number	Diff line change
`@@ -998,4 +998,4 @@`
`998`	`998`	`"deprecated": false`
`999`	`999`	`}`
`1000`	`1000`	`]`
`1001`		`-}`
	`1001`	`+}`
Original file line number	Diff line number	Diff line change
`@@ -195,4 +195,4 @@`
`195`	`195`	"description": "Create an initial application that does not utilize `zone.js`."
`196`	`196`	`}`
`197`	`197`	`]`
`198`		`-}`
	`198`	`+}`
Original file line number	Diff line number	Diff line change
`@@ -2022,6 +2022,7 @@ export abstract class ViewContainerRef {`
`2022`	`2022`	`// @public`
`2023`	`2023`	`export enum ViewEncapsulation {`
`2024`	`2024`	`Emulated = 0,`
	`2025`	`+ IsolatedShadowDom = 4,`
`2025`	`2026`	`None = 2,`
`2026`	`2027`	`ShadowDom = 3`
`2027`	`2028`	`}`