Isolated Mode Experimental

By default every PrimeVue app on a page shares one theme. Its styles go to the document head and its design tokens to :root, so a second app on that page restyles the first one, and an app inside a shadow root does not see the styles at all.

Isolated mode gives an app its own theme. The app's root element and its overlays carry a data-p-theme attribute with the app's key, every rule is scoped to that attribute, and its styles go into each root the app 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 app that is alone on its page does not need it. The API is experimental and may change based on feedback.

Pass the result of withIsolation to the isolation option and keep the rest of the configuration.

The key names the app's scope. It may contain letters, digits, _ and -, up to 128 characters. Without a key the browser picks a random one. When another app on the page already holds the key, the new app gets a -2, -3 suffix.

Server-side rendering requires a key, so that the server and the browser use the same one.

With Nuxt, the module renders the app's root element with the key and writes the styles on the server. With another server renderer, render the container with data-p-theme set to the key and add the result of getIsolatedStyleSheets to the head, so the page is styled before the client loads. The client takes these styles over on hydration.

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 app 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 app owns the page: enable cssLayer, so overrides written for the app 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 app in a shadow root. Isolated mode places its styles there.

useIsolation returns the isolation of the current app, or undefined in the default mode. Use retain to bring the app's styles into a shadow root it does not render in yet, hold to put an element appended outside the app inside its scope, and set with scopeCSS to add custom CSS to the app's scope.

An app that keeps the default mode but renders components inside shadow roots uses withShadowRoot instead, which copies the page styles into the shadow roots that PrimeVue components render in. Isolated mode already does this, so the two options are not combined.

Isolated mode keeps the app's theme and styles apart from other apps. It does not stop CSS on the page from matching the app's elements; only a shadow root does that. One isolated app inside another is not supported.