FlexWait Documentation

Markup

A FlexWait can be created declaratively by adding the flexwait class to a <div>. Declarative FlexWaits are initialized in a hidden state and are controlled through their instance.

This overlay example uses the documented defaults except for mode, text, backdrop, and pointer blocking.

<section id="productResults">
    <div id="productWait"
         class="flexwait"
         data-mode="overlay"
         data-text="Loading products..."
         data-backdrop="true"
         data-block-interaction="true"></div>

    <!-- Product content -->
</section>

const productWait = FlexWait.get("#productWait");
productWait.show();

try {
    await loadProducts();
}
finally {
    productWait.hide();
}

A FlexWait can also be created programmatically. Pass an Element, id, or selector as target. If no target is supplied, the component is appended to the document body.

const wait = FlexWait.create({
    target: document.getElementById("productResults"),
    mode: "overlay",
    variant: "dots",
    size: "large",
    text: "Loading products...",
    backdrop: true
});

wait.show();

Use an operation token when multiple asynchronous operations share one loader. Calling end() more than once on the same token is safe.

const productsOperation = wait.begin();
const filtersOperation = wait.begin();

loadProducts().finally(() => productsOperation.end());
loadFilters().finally(() => filtersOperation.end());

Default configuration

Use FlexWait.configure(<options object>) before initialization to change the defaults for FlexWaits created afterwards.

FlexWait.configure({
    mode: "inline",
    variant: "ring",
    size: "medium",
    thickness: "3px",
    text: "",
    textPosition: "below",
    ariaLabel: "Loading",
    animationDuration: 800,
    showDelay: 150,
    minimumVisibleDuration: 300,
    timeout: 0,
    backdrop: false,
    blockInteraction: false,
    styles: {
        color: "currentColor",
        trackColor: "rgba(0, 0, 0, 0.12)",
        backdropColor: "rgba(255, 255, 255, 0.72)",
        borderRadius: "8px",
        zIndex: 1000,
        cssClass: ""
    }
});

Data-attributes

Data-attributes configure an individual declarative FlexWait and override the corresponding default configuration.

Attribute	Values	Description
class	flexwait	Mandatory. Transforms the <div> into a FlexWait.
data-target-id	Element id	Optional. Default: the FlexWait element's parent. Moves the FlexWait into the target and applies aria-busy to that target while waiting.
data-mode	inline, overlay, fullscreen	Optional. Default: inline.
data-variant	ring, dots, bars, pulse, orbit	Optional. Default: ring.
data-size	small, medium, large, or CSS length	Optional. Default: medium (32px). Presets are small (16px), medium (32px), and large (56px).
data-thickness	CSS length	Optional. Default: 3px. Controls the ring or orbit track thickness.
data-text	Text	Optional. Default: an empty string. Displays status text beside or below the animation.
data-text-position	below, right	Optional. Default: below.
data-aria-label	Text	Optional. Default: Loading. Accessible name for the status element.
data-animation-duration	Milliseconds, zero or greater	Optional. Default: 800. Duration of one animation cycle.
data-show-delay	Milliseconds, zero or greater	Optional. Default: 150. Avoids flashing the loader for very fast operations. The target receives aria-busy="true" immediately, before the visual delay.
data-minimum-visible-duration	Milliseconds, zero or greater	Optional. Default: 300. Once shown, the loader remains visible for at least this duration.
data-timeout	Milliseconds, zero or greater	Optional. Default: 0 (disabled). Hides the loader and emits flexwait:timeout. It does not cancel the underlying request.
data-backdrop	true, false	Optional. Default: false. Displays the configured backdrop in overlay and fullscreen modes.
data-block-interaction	true, false	Optional. Default: false. Intercepts pointer interaction within the overlay. It does not manage keyboard focus.
styles		Visual options for an individual FlexWait.
data-styles-color	CSS color	Optional. Default: currentColor.
data-styles-track-color	CSS color	Optional. Default: rgba(0, 0, 0, 0.12).
data-styles-backdrop-color	CSS color	Optional. Default: rgba(255, 255, 255, 0.72).
data-styles-border-radius	CSS length	Optional. Default: 8px. Applies to an element overlay; fullscreen mode always uses zero.
data-styles-z-index	Integer	Optional. Default: 1000.
data-styles-css-class	One or more CSS class names	Optional. Default: an empty string. Adds custom class names to the FlexWait root.

Designs and modes

Designs

Variant	Best suited for
ring	General-purpose loading. This is the default.
dots	Compact or conversational interfaces.
bars	Data processing or activity-oriented states.
pulse	Subtle inline and overlay feedback.
orbit	Prominent overlays and fullscreen waiting.

Modes

Mode	Behaviour
inline	Participates in the normal document flow and inherits the surrounding text color by default.
overlay	Covers its target. FlexWait temporarily gives a statically positioned target position: relative and restores the original inline value on destruction.
fullscreen	Covers the viewport and is appended to the document body.

FlexWait respects prefers-reduced-motion by slowing animations and removing the opacity transition.

Events

Events bubble from the FlexWait root. Every event exposes the instance as event.detail.instance.

Event	Description
flexwait:show	Emitted when the visual loader is shown after any configured delay.
flexwait:hide	Emitted when the visual loader is hidden after its minimum visible duration.
flexwait:timeout	Emitted when the configured timeout expires, immediately before FlexWait requests hiding.

API

Method	Parameters and return value	Description
FlexWait.configure(options)	options: partial configuration object. Returns nothing.	Deep-merges options into the defaults used by FlexWaits created afterwards.
FlexWait.initialize()	Returns the array of registered instances.	Initializes every uninitialized element with the flexwait class. It is called on DOMContentLoaded.
FlexWait.create(options)	options: configuration object with an optional target Element, id, or selector. Returns the new FlexWait instance.	Creates a hidden programmatic FlexWait and appends it to its target.
FlexWait.get(elementOrSelector)	Accepts an Element or selector. Returns its FlexWait instance or null.	Retrieves an initialized declarative or programmatic instance.
myFlexWait.show()	Returns the same instance for chaining.	Marks the target busy immediately, then displays the loader after showDelay.
myFlexWait.hide()	Returns the same instance for chaining.	Cancels a pending show or hides a visible loader after minimumVisibleDuration. Direct hiding also clears active operation tokens.
myFlexWait.begin()	Returns an operation token with an idempotent end() method.	Shows the loader and increments its active-operation count. The loader hides after the last operation token ends.
myFlexWait.setText(text)	Returns the same instance for chaining.	Updates only the status text without rebuilding the loader or its host content.
myFlexWait.destroy()	Returns nothing.	Clears timers and busy state, restores target positioning when applicable, unregisters the instance, and removes its element.