Adding Loading Indicators to Widgets

#Intended Audience

This tutorial is for:

• Frontend developers integrating Sportradar widgets
• UX engineers improving perceived performance during widget loading
• Developers familiar with basic widget integration
• Those wanting to enhance user experience with loading states

#Goals

By completing this tutorial, you will:

• Understand the widget loading lifecycle and timing
• Implement a custom loading indicator for widgets
• Use the onTrack callback to detect when widgets are ready
• Handle the transition from loading state to loaded widget
• Troubleshoot common loading indicator issues
• Improve perceived performance with visual feedback

#Prerequisites

Before starting this tutorial, ensure you have:

• Valid Sportradar Widget license - Contact Sales if needed
• Basic HTML/CSS/JavaScript knowledge - DOM manipulation, CSS animations, event handling
• Completed Getting Started Guide - Understanding of basic widget integration
• Web development environment - Text editor and modern browser

#Overview

#Understanding Widget Loading Phases

Widget loading happens in multiple asynchronous phases:

1. Script download - Widgetloader framework is fetched
2. Widget registration - SIR function becomes available
3. Widget initialization - Widget code replaces target element content
4. Data fetching - Widget requests match/tournament data
5. Rendering - Widget displays components or error

#The Challenge

Users see a blank space while widgets load, which can:

• Create confusion about whether the page is working
• Make the page feel slow or broken
• Reduce user confidence in your integration

A loading indicator provides visual feedback that content is on the way.

#Tutorial Steps

#Step 1: Understand the Basic Widget Integration

Start with a standard widget integration. The widgetloader script downloads asynchronously, then the SIR function loads the widget.

<script>
    (function(a,b,c,d,e,f,g,h,i){a[e]||(i=a[e]=function(){(a[e].q=a[e].q||[]).push

#What Happens During Loading

#Step 2: Create the Loading Indicator

Add a separate element for your loading indicator. Keep it outside the widget's target element.

#HTML Structure

<div class="widgets">
    <!-- Widget target element - will be populated by widget code -->
    <div id="sr-widget-1" class="box"></div>
    
    <!-- Separate element for loading indicator -->
    <div id="your-content" class="box">
        <div class="loader"></div>
    </div>
</div>

#CSS Styling

Add styles to size the elements and animate the loader.

body {
    display: flex;
    justify-content: center;
}

.widgets {
    max-width: 360px;
    width: 100%;
}

/* Set same size for widget and loader containers */
.box {
    border

#Visual Result

#Step 3: Implement the Loading State Logic

Use the onTrack callback to detect when the widget has loaded data, then swap visibility between the loader and widget.

#Add the onTrack Callback Function

let widgetHasInitialized = false;

function onTrack(target, data) {
    // Listen for 'data_change' event - fired when widget receives data
    if (target === "data_change" && !data.error && !widgetHasInitialized) {
        // Show the widget
        document.getElementById('sr-widget-1').style.display =

#Pass onTrack to Widget Configuration

SIR("addWidget", "#sr-widget-1", "match.scoreboard", {
    matchId: 41960917,
    onTrack: onTrack
});

#Hide Widget Initially With CSS

Add CSS to hide the widget element until data loads.

/* Hide widget until data loads */
#sr-widget-1 {
    display: none;
}

#Complete Integration

<!DOCTYPE html>
<html>

#Troubleshooting

#Issue: Loading Indicator Disappears Too Early

Symptom: The loading indicator vanishes before the widget displays, leaving a blank space.

Cause: The loading indicator was placed inside the widget's target element.

Incorrect Implementation:

<!-- ❌ DON'T DO THIS -->
<div id="sr-widget-1" class="box">
    <!-- This will be removed when widget initializes! -->
    <div id="your-content" class="box">
        <div class="loader"></div>
    </div>
</div>

Correct Implementation:

<!-- ✅ DO THIS -->
<div class="widgets">
    <!-- Widget target - empty, will be filled by widget -->
    <div id="sr-widget-1" class="box"></div>
    
    <!-- Loader in separate element -->
    <div id="your-content" class="box">
        <div class="loader"></div>
    </div>
</

#Issue: Widget Shows Before Data Loads

Cause: Forgot to hide the widget element initially with CSS.

Solution: Add CSS to hide the widget until data_change fires:

#sr-widget-1 {
    display: none;
}

#Issue: Both Loader and Widget Visible

Cause: The onTrack callback isn't firing or has incorrect logic.

Solution: Verify:

1. onTrack is passed to widget configuration
2. Element IDs match exactly
3. You're checking for target === "data_change"
4. Browser console shows no JavaScript errors

#Advanced: Handling Errors

You can extend the onTrack callback to handle loading errors:

function onTrack(target, data) {
    if (target === "data_change" && !widgetHasInitialized) {
        widgetHasInitialized = true;
        
        if (data.error) {
            // Handle error state
            document.getElementById('your-content').innerHTML = 

#Key Takeaways

#Further Reading

#Core Documentation

• Getting Started Guide - Basic widget integration
• Widget Events (onTrack) - Complete event reference
• Widget Configuration - All configuration options

#Related Tutorials

• Widget Visibility in Carousels - Managing visibility in dynamic layouts
• Error Handling - Comprehensive error handling guide

#Performance Resources

• Web.dev: Perceived Performance - Why loading indicators matter
• MDN: CSS Animations - Creating custom loaders
• MDN: display Property - Understanding display values