Configuring loading visuals

This guide explains how to customise the loading visuals shown when the embedded application is booting. You can define different types of loaders such as spinners, ellipsis animations, skeleton screens, and more.


What is a loading visual?

A loading visual provides feedback to users while the embedded application is preparing to render. This is particularly useful when the application requires some time to load and you want to enhance the user experience by indicating progress.


Configuring loading visuals in your integration

The initial_loading_asset field in the snippet configuration determines what type of loading visual will be displayed. The types available include:

  • spinner - A rotating circle indicator, commonly used to signal loading or processing states.
  • ellipsis - Three animated dots indicating ongoing activity, often used for brief operations or waiting states.
  • skeleton - Placeholder blocks resembling the expected UI structure, offering a visual hint of the content being loaded. Particularly effective for content-heavy pages.
  • pulse - A pulsing ring animation creating a smooth and gentle loading effect. Suitable for background tasks or passive waiting states.
  • none - Disables the loading visual completely.

Default loading visual

If the initial_loading_asset field is omitted from your configuration, the default loading visual used is:

...  
initial_loading_asset: {  
  type: 'spinner',  
  size: 40,  
  stroke: 4,  
  color: '#242424'  
}  
...  

This default spinner is a rotating circle loader, providing a general-purpose visual indicator that the application is in the process of loading.


Available configurations

spinner

A simple rotating spinner often used for general-purpose loading indicators. The size, stroke, and colour can be customised.
spinner example

Optional Fields: size, stroke, color

...  
initial_loading_asset: {  
  type: 'spinner',  
  size: 40,                // Diameter of the spinner in pixels.  
  stroke: 4,               // Thickness of the spinner line.  
  color: '#328CF1'         // Colour of the spinner.  
},  
...  

ellipsis

A minimalistic loading indicator consisting of three bouncing dots. Commonly used for short, asynchronous tasks.
ellipsis example

Optional Fields: size, color

...  
initial_loading_asset: {  
  type: 'ellipsis',  
  size: 12,                // Size of each dot in pixels.  
  color: '#328CF1'         // Colour of the dots.  
},  
...  

skeleton

Skeleton loaders provide visual placeholders representing the structure of content being loaded. They can be configured to render as a grid of placeholders, mimicking the layout of the content being loaded. If no grid configuration is provided, the skeleton loader will fill the entire frame, offering a seamless loading effect for full-page or standalone component applications.
skeleton example

Optional Fields: width, height, borderRadius, baseColor, highlightColor, shimmer, grid

...  
initial_loading_asset: {  
  type: 'skeleton',  
  width: '100%',           // Width of the skeleton block or grid.  
  height: '100%',          // Height of the skeleton block or grid.  
  borderRadius: '8px',     // Rounding of the skeleton's corners.  
  baseColor: '#e2e2e2',    // Base background colour.  
  highlightColor: '#f5f5f5', // Highlight colour for shimmering effect.  
  shimmer: true,           // Whether to enable shimmering animation.  
  grid: {  
    columns: 3,            // Number of columns in a grid layout.  
    rows: 2,               // Number of rows in a grid layout.  
    gap: '10px',           // Space between grid items.  
    padding: '10px'        // Padding around grid items.  
  }  
},  
...  

pulse

A visually appealing pulsing ring animation that gently expands and fades, creating a subtle feedback effect.
pulse example

Optional Fields: size, color, borderWidth

...  
initial_loading_asset: {  
  type: 'pulse',  
  size: 50,                // Diameter of the pulsing circle in pixels.  
  color: '#328CF1',        // Colour of the pulse animation.  
  borderWidth: 3           // Thickness of the ring.  
},  
...  

none

This disables the loading visual entirely.

...  
initial_loading_asset: {  
  type: 'none'  
},  
...  

Best Practices

  • Use skeleton loaders when you want to provide a preview of the UI structure, giving users a hint of what content is being loaded.
  • Use spinners or ellipsis loaders for generic loading indicators that do not require structural representation.
  • Use pulse loaders for non-intrusive and visually appealing loading feedback.
  • Ensure loading visuals are styled to match your brand’s colour scheme and aesthetics.
  • Test different loader types to determine which provides the best user experience for your specific use case.

For more details on how to configure loading visuals, refer to the relevant section in the Web SDK Reference Guide.

Was this page helpful?