Component reference
LoadingOverlay
Block a local action while work is in progress.
Preview
Live previewOptional six-digit hex. Clear to restore the preset. Check contrast with your brand color.
Changes apply to this preview only.
Width adapts to the available space
"use client";
import { useState } from "react";
import {
Button,
LoadingOverlay,
Card,
CardHeader,
CardTitle,
CardDescription,
CardContent
} from "@pimolu/react";
function ControlledLoadingDemo() {
const [loading, setLoading] = useState(true);
return (
<div className="grid gap-5 min-w-0">
<div className="flex flex-wrap items-center gap-3 min-w-0">
<Button
size="sm"
appearance="outline"
onClick={() => setLoading((value) => !value)}
>
{loading ? "Stop loading" : "Start loading"}
</Button>
<span className="text-sm text-muted leading-relaxed">
aria-busy={String(loading)} · the covered button cannot be
focused
</span>
</div>
<LoadingOverlay
loading={loading}
label="Loading the dashboard"
description="Metrics, invoices and activity arrive together."
>
<Card>
<CardHeader>
<CardTitle>Workspace overview</CardTitle>
<CardDescription>
The content underneath stays in the tree, inert and hidden from
assistive technology.
</CardDescription>
</CardHeader>
<CardContent>
<div className="flex flex-wrap items-center gap-3 min-w-0">
<Button size="sm">Open a report</Button>
<span className="text-sm text-muted leading-relaxed">This button is behind the overlay.</span>
</div>
</CardContent>
</Card>
</LoadingOverlay>
</div>
);
}
export function DemoExample() {
return (<ControlledLoadingDemo />);
}More examples
Different configurations and compositions using the real Pimolu API. Each preview runs independently and follows the site appearance.
Blur
blur filters the covered content and blurs the backdrop behind the message.
Saving settings
A saving settings composition using LoadingOverlay.
Preparing an export
A preparing an export composition using LoadingOverlay.
Usage
Use a loading overlay for an actual pending task and always provide completion/error recovery.
API reference
Generated from the public TypeScript declarations. Native HTML attributes are inherited where the component extends them; this reference includes Pimolu props and selected common native attributes.
PimoluLoadingOverlayProps
Type source| Name | Type | Default | Description |
|---|---|---|---|
loading | boolean | undefined | true | Whether the overlay is visible. Defaults to true. |
label | string | undefined | "Loading" | Visible and announced loading message. |
description | ReactNode | — | Optional supporting text shown under the label. |
blur | boolean | undefined | false | Blurs the covered content while loading. |
fullscreen | boolean | undefined | false | Covers the whole viewport with fixed positioning. |
children | ReactNode | — | Content covered by the overlay. It is inert while loading. |
onChange | ChangeEventHandler<HTMLDivElement, Element> | undefined | — | Standard React/HTML attribute. |
defaultValue | string | number | readonly string[] | undefined | — | Standard React/HTML attribute. |
className | string | undefined | — | Standard React/HTML attribute. |
style | CSSProperties | undefined | — | Standard React/HTML attribute. |
aria-label | string | undefined | — | Defines a string value that labels the current element. |
onClick | MouseEventHandler<HTMLDivElement> | undefined | — | Standard React/HTML attribute. |
loadingboolean | undefinedDefault: true
Whether the overlay is visible. Defaults to true.
labelstring | undefinedDefault: "Loading"
Visible and announced loading message.
descriptionReactNodeNo default extracted.
Optional supporting text shown under the label.
blurboolean | undefinedDefault: false
Blurs the covered content while loading.
fullscreenboolean | undefinedDefault: false
Covers the whole viewport with fixed positioning.
childrenReactNodeNo default extracted.
Content covered by the overlay. It is inert while loading.
onChangeChangeEventHandler<HTMLDivElement, Element> | undefinedNo default extracted.
Standard React/HTML attribute.
defaultValuestring | number | readonly string[] | undefinedNo default extracted.
Standard React/HTML attribute.
classNamestring | undefinedNo default extracted.
Standard React/HTML attribute.
styleCSSProperties | undefinedNo default extracted.
Standard React/HTML attribute.
aria-labelstring | undefinedNo default extracted.
Defines a string value that labels the current element.
onClickMouseEventHandler<HTMLDivElement> | undefinedNo default extracted.
Standard React/HTML attribute.
Accessibility
- Announce busy state without trapping focus indefinitely or concealing critical cancellation controls.