Loading Overlay
Semi-transparent surface-overlay with backdrop blur covering a container or page. Centers a spinner with optional progress text.
<arc-loading-overlay>Overview
LoadingOverlay provides a blocking loading state for containers or the entire page. It renders a semi-transparent surface-overlay with backdrop blur that covers its parent element (or the full viewport in global mode), centering a spinner with an optional progress message.
Use loading-overlay when a section of the UI is temporarily unavailable: fetching data, processing a submission, or waiting for an external service. Unlike spinner (which is a small inline indicator), loading-overlay communicates that the entire region is blocked and prevents user interaction until loading completes.
In container mode, the overlay is positioned absolutely within its parent and covers only that element. In global mode, it uses fixed positioning to cover the entire viewport, blocking all interaction across the page. The overlay includes a focus trap in global mode to prevent keyboard users from tabbing behind it.
Guidelines
When to use
- Use loading-overlay for operations that block the entire container or page
- Provide a descriptive message like "Saving changes..." to set user expectations
- Use global mode sparingly, only for full-page blocking operations like an initial data load
- Remove the overlay immediately when loading completes. Avoid artificial delays
- Set the parent container to position: relative when using container mode
When not to use
- Do not use loading-overlay for background operations that don't block the UI. Use spinner instead
- Do not leave the overlay active indefinitely. Always include error handling and timeouts
- Do not stack multiple loading overlays on the same page
- Do not use loading-overlay when the content shape is known. Prefer skeleton placeholders
- Do not use global mode for section-level loading. It blocks the entire application unnecessarily
Features
- Semi-transparent overlay with backdrop blur effect
- Centered spinner with configurable progress message
- Container mode: covers the parent element with position: absolute
- Global mode: covers the full viewport with position: fixed and a focus trap
- Prevents pointer events and keyboard interaction behind the overlay
- Smooth fade-in and fade-out transitions
- Accessible: aria-busy="true" on the overlay container
- Respects `prefers-reduced-motion`: disables blur and fade when set
- Composable: uses spinner internally
Preview
Content behind the loading overlay
Usage
This component requires JavaScript. No pure HTML/CSS version is available. Use the Web Component directly or a framework wrapper.
<!-- Container mode -->
<div style="position: relative; min-height: 200px;">
<arc-loading-overlay active message="Loading data..."></arc-loading-overlay>
<p>Content behind the overlay</p>
</div>
<!-- Global mode -->
<arc-loading-overlay active global message="Please wait..."></arc-loading-overlay>import { LoadingOverlay } from '@arclux/arc-ui-react';
export function LoadingDemo() {
const [loading, setLoading] = useState(true);
return (
<div style={{ position: 'relative', minHeight: 200 }}>
<LoadingOverlay active={loading} message="Loading data..." />
<p>Content behind the overlay</p>
</div>
);
}<script setup>
import { ref } from 'vue';
import { LoadingOverlay } from '@arclux/arc-ui-vue';
const loading = ref(true);
</script>
<template>
<div style="position: relative; min-height: 200px;">
<LoadingOverlay :active="loading" message="Loading data..." />
<p>Content behind the overlay</p>
</div>
</template><script>
import { LoadingOverlay } from '@arclux/arc-ui-svelte';
let loading = true;
</script>
<div style="position: relative; min-height: 200px;">
<LoadingOverlay active={loading} message="Loading data..." />
<p>Content behind the overlay</p>
</div>import { Component } from '@angular/core';
import { LoadingOverlay } from '@arclux/arc-ui-angular';
@Component({
imports: [LoadingOverlay],
template: `
<div style="position: relative; min-height: 200px;">
<arc-loading-overlay [active]="loading" message="Loading data..."></arc-loading-overlay>
<p>Content behind the overlay</p>
</div>
`,
})
export class LoadingDemoComponent {
loading = true;
}import { LoadingOverlay } from '@arclux/arc-ui-solid';
import { createSignal } from 'solid-js';
export function LoadingDemo() {
const [loading, setLoading] = createSignal(true);
return (
<div style={{ position: 'relative', 'min-height': '200px' }}>
<LoadingOverlay active={loading()} message="Loading data..." />
<p>Content behind the overlay</p>
</div>
);
}import { LoadingOverlay } from '@arclux/arc-ui-preact';
import { useState } from 'preact/hooks';
export function LoadingDemo() {
const [loading, setLoading] = useState(true);
return (
<div style={{ position: 'relative', minHeight: 200 }}>
<LoadingOverlay active={loading} message="Loading data..." />
<p>Content behind the overlay</p>
</div>
);
}API
messagestring''- Optional text displayed below the spinner. Use it to communicate what is loading or the current progress step.
activebooleanfalse- Controls whether the loading overlay is visible. When true, the overlay fades in and blocks interaction with the content behind it.
globalbooleanfalse- When true, the overlay uses fixed positioning to cover the entire viewport instead of just its parent container. Includes a focus trap in this mode.