REST API Usage 07: Custom Loading Indicators

This QuickStart demonstrates how to implement custom loading indicators for Sigma embeds that display while a workbook is loading.

The host application listens for Sigma's workbook:dataLoaded postMessage event to determine when to hide the loading indicator—ensuring a smooth user experience during embed initialization.

REST API Usage 01: Getting Started

For more information on Sigma's product release strategy, see Sigma product releases

If something doesn't work as expected, here's how to contact Sigma support

Target Audience

Developers who want to use Sigma's REST API to programmatically control Sigma in an embedded context.

Prerequisites

Any modern browser will work.
Access to your Sigma environment.
Some familiarity with Sigma is assumed. Not all steps are shown, as the basics are assumed understood.
Microsoft VSCode or other suitable development tool.

Sigma Free Trial

Download Visual Studio Code

Footer

Start the Express server in terminal from the embedding_qs_series_2_api_use_cases folder and enable debugging:

DEBUG=true npm start

The server is ready when it displays: Server listening at http://localhost:3000.

Browse to the landing page:

http://localhost:3000

Select the Loading Indicators page and click Go.

Footer

Select the Build user and any available workbook from the dropdown menus.

Once a workbook is selected, the iframe area becomes translucent and a loading indicator is displayed. The indicator uses a simple CSS spinner:

There are many ways to implement custom loaders; in this case, we chose a lightweight CSS-based approach and centralized the styling in the /styles/main.css file. This allows the same loading logic to be reused across other project pages without duplicating code.

The relevant styles begin in the section labeled CENTRALIZED LOADING INDICATORS within main.css.

/* ============================================================================
   CENTRALIZED LOADING INDICATORS
   ============================================================================ */

/* Loading Overlay for Embeds */
.embed-loading-overlay {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  background: rgba(255, 255, 255, 0.9);
  display: flex;
  justify-content: center;
  align-items: center;
  z-index: 1000;
  border-radius: var(--border-radius);
}

/* Loading Spinner Container */
.loading-spinner {
  background: white;
  padding: 2rem;
  border-radius: var(--spacing-sm);
  text-align: center;
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
  border: 1px solid #e0e0e0;
}

/* Animated Spinner */
.loading-spinner .spinner {
  width: 40px;
  height: 40px;
  border: 4px solid var(--border-light);
  border-top: 4px solid var(--primary-color);
  border-radius: 50%;
  animation: spin 1s linear infinite;
  margin: 0 auto 1rem auto;
}

/* Loading Text */
.loading-spinner .loading-text {
  color: var(--secondary-color);
  font-size: 16px;
  font-weight: 500;
  font-family: var(--font-family);
}

/* Iframe Translucency During Loading */
iframe.loading {
  opacity: 0.85;
  transition: opacity 0.3s ease;
}

iframe:not(.loading) {
  opacity: 1;
  transition: opacity 0.3s ease;
}

Footer

To determine when an embed has fully loaded, the host application listens for Sigma's outbound JavaScript event: workbook:dataLoaded. When this event is received, the application hides the custom loader—ensuring users see a loading indicator during initialization and the embed only appears once it's ready.

For example, the screenshot below shows the workbook:dataLoaded event firing. The final two log entries are additional messages from the sample code used for validation:

Error Handling

In some cases, an embed may fail to load within a reasonable timeframe. To account for this, the sample implementation includes a 30-second timeout. If the embed doesn't load within that window, a popup appears instructing the user to reload the page.

This timeout is included for demonstration purposes only and can be adjusted or removed based on your use case.

Loading Indicator Functions

The design is intentionally self-contained in a single index.html file, making it easy to understand and modify. All logic related to the loader, event handling, and UI feedback is placed in the script section of that file.

Here's how the logic is organized:

// UTILITY FUNCTIONS (lines 167–218)

showEmbedLoader() – Displays the custom loading overlay
hideEmbedLoader() – Hides the loading overlay
showLoadingError() – Displays an error message after timeout
base64UrlDecode() – Decodes JWTs (not related to loading)

// SIGMA EMBED EVENT HANDLING (lines 144–164)

window.addEventListener("message", ...) – Listens for workbook:dataLoaded and calls hideEmbedLoader() when the event is received

// SIGMA EMBED FUNCTIONS (line 257+)

loadEmbed() – Initiates the embed load and triggers showEmbedLoader()

This structure follows a clear separation of concerns:

Utility functions are grouped together
Event handling is centralized
Embed logic is isolated in its own section

The 30-second timeout is implemented in showEmbedLoader() (lines 184-190) using setTimeout() and is a key safety feature that ensures users get feedback if the Sigma embed fails to load or doesn't send the expected workbook:dataLoaded event within 30 seconds.

Footer

In this QuickStart, you learned how to implement a custom loading indicator for Sigma embeds using the `workbook:dataLoaded event from the PostMessage API. We covered:

Displaying a CSS-based loading overlay while the workbook loads
Listening for the workbook:dataLoaded event to hide the loader at the right time
Handling loading errors with a timeout and fallback messaging
Structuring loader logic using utility functions, event listeners, and embed triggers

This pattern helps create a smoother, more professional embed experience while giving you full control over how and when content is shown to users.

Additional Resource Links

Blog
Community
Help Center
QuickStarts

Be sure to check out all the latest developments at Sigma's First Friday Feature page!

Footer