ShadowDOM Widget Integration Tutorial

#Intended Audience

This tutorial is for:

• Advanced frontend developers working with Web Components and ShadowDOM
• Technical integrators building encapsulated component architectures
• Developers familiar with JavaScript DOM manipulation and the ShadowDOM API
• Those who have completed basic widget integration and need ShadowDOM support

#Goals

By completing this tutorial, you will:

• Understand how to integrate widgets inside ShadowDOM containers
• Learn to pass DOM element references instead of CSS selectors
• Implement a MutationObserver to clone widget styles into ShadowDOM
• Create a complete, working ShadowDOM widget integration
• Handle both open and closed ShadowDOM modes

#Prerequisites

Before starting this tutorial, ensure you have:

• Valid Sportradar Widget license - Contact Sales if needed
• Client ID - Provided with your license
• JavaScript knowledge - Understanding of:
  • DOM manipulation
  • ShadowDOM API (attachShadow, shadow roots)
  • MutationObserver API
  • ES6+ syntax
• Basic widget integration experience - Completed Getting Started Guide
• Web development environment - Text editor and modern browser with ShadowDOM support (Chrome, Firefox, Safari, or Edge)
• Match ID - A valid match identifier for testing

#Overview

ShadowDOM provides style and DOM encapsulation for web components, but this encapsulation presents two challenges for widget integration:

1. CSS selectors don't work - Widget container inside ShadowDOM cannot be targeted with standard selector strings, so direct DOM element must be passed instead
2. Styles are isolated - Widget styles injected into <head> are not visible inside ShadowDOM, so they need to be cloned into the ShadowDOM.

This tutorial shows you how to overcome both challenges.

#Tutorial Steps

#Step 1: Create ShadowDOM Container

First, create a host element and attach a shadow root to it. Then create a container element inside the shadow root where the widget will be rendered.

<div id="widget-host"></div>

const host = document.getElementById('widget-host');
const shadowRoot = host.attachShadow({ mode: 'open' });
const widgetContainer = document.createElement('div');
shadowRoot.appendChild(widgetContainer);

#Step 2: Pass DOM Element Reference to Widget API

When working with ShadowDOM, you cannot use CSS selector strings with SIR('addWidget'). Instead, pass a direct reference to the container DOM element.

SIR('addWidget', '#widget-container', 'match.lmtPlus', { ... });

SIR('addWidget', widgetContainer, 'match.lmtPlus', { ... }

Example initialization:

// Include widgetloader
(function(a,b,c,d,e,f,g,h,i){a[e]||(i=a[e]=function(){(a[e].q=a[e].q||[]).push(arguments)},i

#Step 3: Set up Style Container

Create a dedicated container inside the ShadowDOM to hold the cloned <link> elements.

const widgetContainer = document.createElement('div');
const linkContainer = document.createElement('div');
shadowRoot.appendChild(linkContainer);
shadowRoot.appendChild(widgetContainer);

#Step 4: Implement MutationObserver for Style Cloning

Widgets inject <link> and <style> elements into the document <head>. These styles are not visible inside ShadowDOM by default. Use a MutationObserver to detect and clone these elements.

#Understanding What to Clone

Only clone widget-specific styles to avoid conflicts:

• <link> elements with href containing widgets.sir.sportradar.com
• <style> element with id="sr-client-theme" (only when using custom themes)

const observer = new MutationObserver(mutations => {
    mutations.forEach(mutation => {
        mutation.addedNodes.forEach(node => {
            // Clone widget stylesheet links
            if (node.tagName ===

#Step 5: Initialize Widget

Now that the observer is in place, initialize the widget as shown in Step 2. The observer will automatically clone styles as they are added to the document.

SIR('addWidget', widgetContainer, 'match.lmtPlus', {
    matchId: 'your_match_id_here'
});

#Complete Implementation

<!DOCTYPE html

#Key Takeaways

#Further Reading

#Sportradar Widget Documentation

• Getting Started Guide - Basic widget integration
• Global SIR API - Complete API reference
• Widget Customization - Theming and styling options

#Web Platform APIs

• ShadowDOM API (MDN) - Comprehensive guide to ShadowDOM
• MutationObserver API (MDN) - Observing DOM changes
• Web Components (MDN) - Building encapsulated components