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
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 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 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
-
activebooleanfalse - Controls whether the loading overlay is visible. When true, the overlay fades in and blocks interaction with the content behind it.
-
messagestring'' - Optional text displayed below the spinner. Use it to communicate what is loading or the current progress step.
-
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.