React Shadow DOM Template Component

A React component that enables easy integration of Shadow DOM functionality in your React applications. This component provides a declarative way to create and manage Shadow DOM with full React compatibility.

Features

• 🔒 Shadow DOM Encapsulation - Isolate styles and DOM structure
• ⚛️ React Compatible - Render React components inside Shadow DOM
• 🎨 Styling Support - Use CSS Stylesheets with adoptedStyleSheets
• ⚙️ Configurable - Full control over Shadow DOM options
• 🔄 Dynamic Updates - Automatically handles prop changes and remounting

Installation

npm i @krasnoff/react-shadow-dom-component

Basic Usage

import React from 'react';
import { Template } from '@krasnoff/react-shadow-dom-component'

function App() {
  return (
    <Template shadowrootmode="open">
      <div style={{ padding: '20px', backgroundColor: 'lightblue' }}>
        <h1>This content is rendered inside Shadow DOM!</h1>
        <p>Styles are encapsulated and won't affect the parent document.</p>
      </div>
    </Template>
  );
}

Advanced Usage with CSS Stylesheets

import React from 'react';
import { Template } from '@krasnoff/react-shadow-dom-component'

function StyledComponent() {
  // Create a CSS stylesheet for the Shadow DOM
  const stylesheet = new CSSStyleSheet();
  stylesheet.replaceSync(`
    .container {
      background: linear-gradient(45deg, #ff6b6b, #4ecdc4);
      padding: 2rem;
      border-radius: 10px;
      color: white;
      font-family: Arial, sans-serif;
    }
    .title {
      font-size: 2rem;
      margin-bottom: 1rem;
    }
  `);

  return (
    <Template 
      shadowrootmode="open" 
      sheet={stylesheet}
      shadowrootdelegatesfocus={true}
    >
      <div className="container">
        <h1 className="title">Styled Shadow DOM Content</h1>
        <p>This component uses adopted stylesheets for styling.</p>
        <button>This button won't be styled by parent CSS!</button>
      </div>
    </Template>
  );
}

Component API

Props

Prop	Type	Default	Description
children	React.ReactNode	undefined	React elements to render inside the Shadow DOM
shadowrootmode	'open' | 'closed'	'open'	Shadow DOM mode - 'open' allows external access, 'closed' doesn't
sheet	CSSStyleSheet	undefined	CSS stylesheet to apply to the Shadow DOM using adoptedStyleSheets
shadowrootclonable	boolean	false	Whether the shadow root can be cloned
shadowrootdelegatesfocus	boolean	false	Whether focus delegation is enabled
shadowrootserializable	boolean	false	Whether the shadow root can be serialized
slotAssignment	'manual' | 'named'	'named'	How slots are assigned in the shadow tree - 'named' for automatic assignment, 'manual' for programmatic control
connectedCallback	(shadowRoot: ShadowRoot, hostElement: HTMLDivElement) => void	undefined	Callback function executed when Shadow DOM is successfully created and connected

TypeScript Interface

export interface TemplateProps {
    children?: React.ReactNode;
    shadowrootmode?: 'open' | 'closed';
    sheet?: CSSStyleSheet;
    shadowrootclonable?: boolean;
    shadowrootdelegatesfocus?: boolean;
    shadowrootserializable?: boolean;
    slotAssignment?: 'manual' | 'named';
    connectedCallback?: (shadowRoot: ShadowRoot, hostElement: HTMLDivElement) => void;
}

Use Cases

1. Widget Isolation

Perfect for creating widgets that need to be embedded in third-party websites without style conflicts:

function EmbeddableWidget() {
  const widgetStyles = new CSSStyleSheet();
  widgetStyles.replaceSync(`
    .widget {
      border: 2px solid #007bff;
      padding: 1rem;
      background: white;
      font-family: -apple-system, BlinkMacSystemFont, sans-serif;
    }
  `);

  return (
    <Template shadowrootmode="open" sheet={widgetStyles}>
      <div className="widget">
        <h3>My Embeddable Widget</h3>
        <p>This widget is completely isolated from the host page!</p>
      </div>
    </Template>
  );
}

2. Micro Frontend Components

Isolate micro frontend components to prevent style bleeding:

function MicroFrontend({ apiEndpoint }: { apiEndpoint: string }) {
  const [data, setData] = useState(null);

  const microfrontendStyles = new CSSStyleSheet();
  microfrontendStyles.replaceSync(`
    .micro-app {
      display: flex;
      flex-direction: column;
      gap: 1rem;
    }
    .card { /* ... */ }
  `);

  return (
    <Template 
      shadowrootmode="open" 
      sheet={microfrontendStyles}
      shadowrootdelegatesfocus={true}
    >
      <div className="micro-app">
        {/* Your micro frontend content */}
      </div>
    </Template>
  );
}

3. Library Components with Theme Isolation

function ThemeIsolatedButton({ theme, children, onClick }: ButtonProps) {
  const buttonTheme = new CSSStyleSheet();
  buttonTheme.replaceSync(`
    .theme-button {
      background: ${theme.primaryColor};
      color: ${theme.textColor};
      padding: ${theme.spacing}px;
      border: none;
      border-radius: ${theme.borderRadius}px;
      cursor: pointer;
      font-size: 1rem;
    }
    .theme-button:hover {
      opacity: 0.8;
    }
  `);

  return (
    <Template shadowrootmode="open" sheet={buttonTheme}>
      <button className="theme-button" onClick={onClick}>
        {children}
      </button>
    </Template>
  );
}

4. Using Slot Assignment

Control how slots are assigned within the Shadow DOM:

function SlotAssignmentExample() {
  return (
    <Template 
      shadowrootmode="open" 
      slotAssignment="named"
    >
      <div>
        <h2>Content with Named Slots</h2>
        <slot name="header"></slot>
        <p>Main content area</p>
        <slot name="content"></slot>
        <footer>
          <slot name="footer"></slot>
        </footer>
      </div>
    </Template>
  );
}

// Usage with slotted content
function App() {
  return (
    <SlotAssignmentExample>
      <div slot="header">This goes in the header slot</div>
      <div slot="content">This goes in the content slot</div>
      <div slot="footer">This goes in the footer slot</div>
    </SlotAssignmentExample>
  );
}

5. Using Connected Callback

Execute custom logic when Shadow DOM is created:

function ConnectedCallbackExample() {
  const handleConnected = (shadowRoot: ShadowRoot, hostElement: HTMLDivElement) => {
    console.log('Shadow DOM connected!', shadowRoot);
    
    // Add custom event listeners
    shadowRoot.addEventListener('click', (e) => {
      console.log('Clicked inside Shadow DOM:', e.target);
    });
    
    // Modify host element
    hostElement.style.border = '2px solid #10b981';
    hostElement.style.borderRadius = '8px';
    
    // Access shadow DOM elements
    const button = shadowRoot.querySelector('.my-button');
    if (button) {
      button.addEventListener('mouseenter', () => {
        console.log('Button hovered');
      });
    }
    
    // Dynamic content updates
    const timestamp = shadowRoot.querySelector('#timestamp');
    if (timestamp) {
      timestamp.textContent = `Connected at: ${new Date().toLocaleTimeString()}`;
    }
  };

  return (
    <Template 
      shadowrootmode="open" 
      connectedCallback={handleConnected}
    >
      <div>
        <h3>Connected Callback Demo</h3>
        <button className="my-button">Click me!</button>
        <p id="timestamp">Connection time will appear here</p>
      </div>
    </Template>
  );
}

Important Notes

Browser Compatibility

• Shadow DOM: Supported in all modern browsers (Chrome 53+, Firefox 63+, Safari 10+)
• Declarative Shadow DOM: Limited support - mainly Chrome 90+
• Adopted Stylesheets: Chrome 73+, Firefox 101+, Safari 16.4+

Behavior

1. Remounting: The component automatically remounts when key props change to ensure Shadow DOM is recreated properly
2. Style Isolation: Styles inside Shadow DOM don't affect the parent document and vice versa
3. Event Handling: Events work normally, with optional focus delegation
4. Slot Assignment: The component uses named slot assignment by default

Performance Considerations

• Shadow DOM creation has a small overhead
• Adopted stylesheets are more performant than inline styles
• The component handles cleanup automatically to prevent memory leaks

License

This project is licensed under the MIT License - see the LICENSE file for details.