Isolated Mode Experimental
Give an application its own theme, so several applications can share a page or render in shadow roots.
Overview #
By default every PrimeNG application on a page shares one theme. Its styles go to the document head and its design tokens to :root, so a second application on that page restyles the first one, and an application inside a shadow root does not see the styles at all.
Isolated mode gives an application its own theme. The application's root element and its overlays carry a data-p-theme attribute with the application's key, every rule is scoped to that attribute, and its styles go into each root the application renders in, the document or a shadow root. Overlays appended to the body and the dark mode follow the same scope.
It is meant for micro frontends, embeddable widgets and web components, and an application that is alone on its page does not need it. The API is experimental and may change based on feedback.
Setup #
Pass withIsolation to providePrimeNG as a feature and keep the rest of the configuration.
Key #
The key names the application's scope. It may contain letters, digits, _ and -, up to 128 characters. Without a key the browser picks a random one. When another application on the page already holds the key, the new application gets a -2, -3 suffix.
Two server-rendered applications need separate keys, because without a key the server uses the application id.
CSS Layer #
Scoping gives the theme rules a higher specificity than a plain selector. A plain rule such as .p-button { ... } loses to the scoped rule, whether it comes from the application or from the host page. cssLayer moves the theme into a cascade layer, and CSS without a layer wins again as in the default mode. Which setting fits depends on who writes the other CSS on the page.
The application owns the page: enable cssLayer, so overrides written for the application work as in the default mode.
The page belongs to someone else, as with a browser extension or an embedded widget: leave cssLayer off, so the page's own .p-button rules do not override the theme's rules. For a full separation from the host CSS, render the application in a shadow root. Isolated mode places its styles there.
Isolation API #
injectIsolation returns the isolation of the current application, or undefined in the default mode. Use retain to bring the application's styles into a shadow root it does not render in yet, hold to put an element appended outside the application inside its scope, and set with scopeCSS to add custom CSS to the application's scope.
Shadow Root #
An application that keeps the default mode needs no option for shadow roots. A component rendered inside a shadow root, such as a component with ViewEncapsulation.ShadowDom, gets the page styles copied into that root while it is alive, and the dark mode selector on the document is mirrored to the shadow host. Isolated mode handles shadow roots on its own.
Limits #
Isolated mode keeps the application's theme and styles apart from other applications. It does not stop CSS on the page from matching the application's elements; only a shadow root does that. One isolated application inside another is not supported.