Skip to content

LoadingRegion

Copy page

A loading region decides when to switch from Dotquilt’s placeholder to your content. It shows its placeholder while your data is pending, keeps your content visible while it refreshes, and hands over when it’s ready. Every loader except TextLoader lives inside one.

Preview
Loading
  • Northwind paid $4,200
  • Globex invoice is overdue
  • Initech paid $3,115
State The placeholder Your content
pending shown hidden, inert and hidden from assistive technology
refreshing a row of marks just above the top edge, or your refresh-indicator visible and usable
ready gone, after the handoff visible

While pending, the region is as tall as the taller of the two: your content is laid out, hidden, so the handoff can read its shape. Once the handoff ends, and while refreshing, the placeholder takes no space and the region is as tall as your content. Give the placeholder your content’s size, so nothing moves when the handoff ends.

While it refreshes, a row of marks sits just above the region’s top edge and the glow drifts along it once, so your content never moves. With reduced motion or a pause the row stays still. Move it with --dotquilt-refresh-gap (6 px above the edge by default), style it through ::part(refresh-thread), or pass your own refresh-indicator instead.

For fast responses, delay and min-display keep the placeholder from flickering: a load shorter than delay never shows it, and a placeholder that did show stays for at least min-display. Values around 150 ms and 500 ms suit most screens.

Going from pending to ready plays the handoff. First the marks take your content’s shape: skeleton lines grow or shrink to each real line of text, blocks and circles reshape to the real image or avatar, typing dots unroll into the message, and a placeholder card or bubble grows to the real one’s size. Then your content wipes in along a soft front, and the marks leave where it passes them. Only what shows takes part: text that is clipped away, such as a visually hidden table header, gets no marks. It takes about a second, and right-to-left text wipes from the right. With reduced motion, a pause, or focus inside the content, it swaps at once. During a view transition it waits for the transition to end, then plays.

ActivityFeed.tsx
'use client';
import { LoadingRegion, SkeletonText } from '@dotquilt/react';
import { useCallback, useEffect, useRef, useState } from 'react';
async function fetchActivity(signal: AbortSignal): Promise<string[]> {
const response = await fetch('/api/activity', { signal });
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
return response.json();
}
export function ActivityFeed() {
const [items, setItems] = useState<string[] | null>(null);
const [refreshing, setRefreshing] = useState(false);
const [failed, setFailed] = useState(false);
const latest = useRef<AbortController | null>(null);
const load = useCallback(() => {
// Only the latest request may update the feed.
latest.current?.abort();
const request = new AbortController();
latest.current = request;
return fetchActivity(request.signal).then(
(next) => {
if (latest.current === request) setItems(next);
},
(error) => {
// A newer request replaced this one; that is not a failure.
if (!request.signal.aborted) throw error;
},
);
}, []);
useEffect(() => {
load().catch(() => setFailed(true));
return () => latest.current?.abort();
}, [load]);
function refresh() {
setRefreshing(true);
// A failed refresh keeps the feed you already have.
load()
.catch(() => {})
.finally(() => setRefreshing(false));
}
return (
<section>
<button type="button" onClick={refresh} disabled={refreshing}>
Refresh
</button>
<LoadingRegion
aria-label="Recent activity"
// Pending hides the content; refreshing keeps it visible and usable.
state={
items === null && !failed
? 'pending'
: refreshing
? 'refreshing'
: 'ready'
}
timing={failed && items === null ? { duration: 0 } : undefined}
placeholder={<SkeletonText lines={3} />}
>
{failed && items === null ? (
<p role="alert">We couldn't load activity. Try again later.</p>
) : (
<ul>
{items?.map((item) => (
<li key={item}>{item}</li>
))}
</ul>
)}
</LoadingRegion>
</section>
);
}
Slot React Holds
placeholder placeholder the loader shown while pending
refresh-indicator refreshIndicator your own cue while refreshing, in place of the row of marks
(default) children your content
Attribute React Type Default Description
state state pending | refreshing | ready ready Whether the content is loading.
cycle cycle string Names one load, so a stale answer can’t settle a newer one.
delay delay number (ms) 0 Wait this long before showing the placeholder. A response inside it shows no placeholder and no handoff, so fast loads don’t flicker. A placeholder already on the page, such as server markup, is never hidden. Up to 10000.
min-display minDisplay number (ms) 0 Once a placeholder shows, keep it at least this long before handing over, so it never flashes. Up to 10000.
timing { duration?, easing? } The handoff’s length and curve. { duration: 0 } swaps at once, for errors.
revealTargets { id, element }[] Parts of your content that settle in turn under a custom handoff, or a TableLoader with a targetProvider. The default handoff doesn’t need them.
motion motion system | paused system system follows the visitor’s reduced-motion setting; paused stills every loader inside.
Event When
dotquilt-handoff-start the handoff begins
dotquilt-handoff-end it finishes; detail.reason is complete, or why it swapped at once
dotquilt-handoff-cancel a newer state or cycle replaced it
dotquilt-error an option was invalid or an animation failed; detail.code says which

In React, use onHandoffStart, onHandoffEnd, onHandoffCancel and onLoaderError.

dotquilt-error doesn’t repeat itself. A configuration problem, such as an invalid speed, reports again only after the option held a valid value in between. A failure while loading, such as an animation that throws, reports at most once per load: the next pending state or new cycle can report it again.

  • Label every region with aria-label, so people know what is loading.
  • Pending content is out of reach: it is inert and hidden from assistive technology until it is ready.
  • Focus is kept: if focus is inside content that becomes pending, it moves to the region; completion never moves it back by itself.
  • Status is yours: announce loading and errors in your own words, for example with a role="status" element outside the region.