Shadow DOM is a web standard that allows you to encapsulate a component's styles and markup, creating a boundary that prevents external styles from affecting the component and vice versa. This isolation is achieved by attaching a separate DOM tree (the "shadow" tree) to an element.

Benefits

Shadow DOM is a perfect fit for Parcels because Parcels are designed to be self-contained modules. Using Shadow DOM for each Parcel provides:

• Complete style isolation: Styles from the host application don't leak into your parcel and vice versa
• Consistent theming: Parcel theming remains consistent regardless of embedding context
• No class name collisions: Prevents conflicts with host application class names
• Better performance: Styles scoped only to your parcel
• Safe integration: Supports modular design without accidental CSS conflicts

Enabling shadow DOM

Shadow DOM is not enabled automatically — teams choose to enable it by wrapping the Parcel's root component in a StyleRootProvider with the useShadowDom option set. A ThemeProvider must also be included to retain Abyss theming inside the Shadow DOM.

import React from 'react';
import { Button } from '@uhg-abyss/web/ui/Button';
import { createTheme } from '@uhg-abyss/web/tools/theme';
import {
  StyleRootProvider,
  ThemeProvider,
} from '@uhg-abyss/web/ui/ThemeProvider';

const theme = createTheme('uhc');

export const ParcelApp = () => {
  return (
    <StyleRootProvider
      useShadowDom
      theme={theme}
      cacheOptions={{ key: 'my-parcel' }}
    >
      <ThemeProvider theme={theme}>
        <div>
          <Button>Hello Parcel!</Button>
        </div>
      </ThemeProvider>
    </StyleRootProvider>
  );
};