Loading Overlay

Blocks a region (or the viewport) with a spinner and optional message while work is in progress. Sets aria-busy on the host and a polite live region on the overlay. Prefer this over base-spinner-wrapper when you need copy, scroll locking, or fullscreen.

freenew

Contained

Wrap the section that should dim. The overlay is positioned to the host.

Invoice #1842

Acme Corp — $1,240.00 due on the 24th. Click simulate to cover this card.

HTML

Installation

Run the following command to add this component to your project:

bash

npx base-ui-cli add loading-overlay

API Reference

For AI agents

Copy a prompt with the registry name, CLI install, and import — or add the Base UI MCP server.

bash

npx -y base-ui-mcp

Base UI provides standalone components. Import the exact elements you want to use into your component.

typescript (Example)

// Install: npx base-ui-cli add loading-overlay
// Paths are relative to aliases.components (default: src/app/components)
import { LoadingOverlayComponent } from './loading-overlay/loading-overlay.component';

@Component({
  selector: 'app-your-component',
  imports: [
    LoadingOverlayComponent
  ],
  template: `...`
})
export class YourComponent {}

API for loading-overlay — generated from JSDoc in the library source.

API reference for loading-overlay
API	Member	Type	Default	Description
`base-loading-overlay`	`class`	`string`	`''`	Extra host classes merged via `cn()`.
`base-loading-overlay`	`visible`	`boolean`	`false`	Shows the blocking overlay.
`base-loading-overlay`	`fullscreen`	`boolean`	`false`	Cover the viewport instead of wrapping projected content.
`base-loading-overlay`	`lockScroll`	`boolean`	`false`	Set `overflow: hidden` on `document.body` while visible (typical for fullscreen).
`base-loading-overlay`	`message`	`string`	`''`	Optional status text announced via a live region.
`base-loading-overlay`	`size`	`SpinnerSize`	`'lg'`	Spinner diameter.
`base-loading-overlay`	`color`	`SpinnerColor`	`'primary'`	Spinner color. Use `inverted` on a dark backdrop.