Skip to content

Skeleton

Copy page

Dotquilt’s skeleton loaders hold the shape of images, text and avatars while they load. A soft glow drifts across the marks. When the region hands over, the marks take your content’s real shape, then the content wipes in as they leave.

Preview
Loading
AL
Ada Lovelace
Analytical engines

Wrote the first published algorithm intended for a machine.

Put a skeleton in a region’s placeholder slot and size it with CSS like any other element: blocks fill their width and take the height you give them, and lines are two rows of marks tall. Your code owns the request; the region only needs to know whether the data is pending or ready.

MemberCard.tsx
'use client';
import { LoadingRegion, SkeletonCircle, SkeletonLine } from '@dotquilt/react';
import { useEffect, useState } from 'react';
interface Member {
name: string;
role: string;
bio: string;
}
async function fetchMember(id: string, signal: AbortSignal): Promise<Member> {
const response = await fetch(`/api/members/${id}`, { signal });
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
return response.json();
}
type Result =
| { status: 'loading' }
| { status: 'done'; member: Member }
| { status: 'failed' };
export function MemberCard({ id }: { id: string }) {
const [result, setResult] = useState<Result>({ status: 'loading' });
useEffect(() => {
const request = new AbortController();
setResult({ status: 'loading' });
fetchMember(id, request.signal)
.then((member) => setResult({ status: 'done', member }))
.catch(() => {
if (!request.signal.aborted) setResult({ status: 'failed' });
});
// A newer id cancels this request, so a stale answer never shows.
return () => request.abort();
}, [id]);
return (
<LoadingRegion
aria-label="Team member"
state={result.status === 'loading' ? 'pending' : 'ready'}
cycle={id}
// An error replaces the placeholder at once, without the handoff.
timing={result.status === 'failed' ? { duration: 0 } : undefined}
placeholder={
<div className="member-skeleton">
<SkeletonCircle />
<SkeletonLine />
<SkeletonLine style={{ width: '60%' }} />
</div>
}
>
{result.status === 'done' && (
<article className="member">
<h3>{result.member.name}</h3>
<p>{result.member.role}</p>
<p>{result.member.bio}</p>
</article>
)}
{result.status === 'failed' && (
<p role="alert">We couldn't load this member. Try again later.</p>
)}
</LoadingRegion>
);
}
// Use it like any other component; it loads again whenever `id` changes.
export function Team() {
return <MemberCard id="ada" />;
}

SkeletonText draws each line two rows of marks tall and spaces the lines 0.5em apart. A line is 18 px tall with the default dots (twice the dot size plus the gap), 17 px with squares and 19 px with dashes. That holds a paragraph’s shape without knowing your text’s line height. To put each line where a line of text sits, so the placeholder is as tall as the same number of lines of text, set its gap and margins from 1lh, the line height it inherits:

.excerpt dotquilt-skeleton-text {
--line: 18px; /* 17px for squares, 19px for dashes */
gap: calc(1lh - var(--line));
margin-block: calc((1lh - var(--line)) / 2);
}

Use margins rather than padding: the idle glow’s copy of the lines spans the padding box, so padding moves it off the lines.

Element React Use
<dotquilt-skeleton-block> SkeletonBlock images, charts and other rectangles
<dotquilt-skeleton-line> SkeletonLine one line of text
<dotquilt-skeleton-circle> SkeletonCircle avatars and icons
<dotquilt-skeleton-text> SkeletonText a paragraph of lines
Attribute Type Default Description
mark dot | dash | square dot The shape of each mark. Dashes suit text lines; squares stay crisp at small sizes.
motion system | paused system system follows the visitor’s reduced-motion setting; paused stills the marks.
speed number 1 How fast the idle glow moves, from above 0 up to 4.
pointer-response none | lift none lift lights the marks around the pointer while the placeholder shows, on devices with a fine pointer.
lines number 3 SkeletonText only: how many lines, up to 50.

In React the props have the same names in camelCase (pointerResponse).

Import alternatives from dotquilt/animations/skeleton and pass them as animations.

Phase Default Also available Options
Idle a soft glow drifts across every 2.8 s pulse: the same glow at your own pace periodMs 800–4000 (2800)
Handoff the marks travel to the content’s real shape (each line’s length, the image, the avatar), then the content wipes in as they leave dissolve: marks fall away as the content fades in duration ms (300), fallPx 0–8 (5)

The marks use a slate that sits inside any app, with a soft teal glow. Change them with custom properties:

.profile {
--dotquilt-color: #627467;
--dotquilt-accent-color: #3f7f86;
}