Skeleton

A spinner says "busy". A skeleton says what is coming: grey bars where the text will be, a circle for the avatar, a block for the image. The page does not jump when the data lands, and the wait feels shorter because the shape is already there.

The shapes are plain CSS classes - .skeleton-text, .skeleton-card and friends - so they work in hand-written HTML. E.skeleton() writes them into a container for you, tells screen readers the container is loading, and puts things back when you are done. E.skeleton.while() does all of that around a promise.

Key Features

• Ready-made shapes - text, card, list and table, or your own markup
• Theme-aware - tinted from the theme's own text and surface, quiet on light and dark
• Promise helper - E.skeleton.while(target, promise) shows it until the promise settles
• Nothing lost - remove() puts back the very same nodes, listeners and all
• Accessible - aria-busy and a polite "Loading..." status; the shapes are hidden from screen readers
• Reduced motion - no sweep, just the still tint
• DataTable - loadingSkeleton: true shows skeleton rows until the data arrives

Basic Usage

const posts = await E.skeleton.while('#posts', H.get('/api/posts'), {type: 'card', count: 3});
$('#posts').html(renderPosts(posts));

A list that shows placeholders while it loads, in three steps

Step 1 - A container

Any element will do. The skeleton goes inside it, so give it the layout the real content will have - a grid for cards, a plain block for a list.

<div id="users"></div>

Step 2 - Show a skeleton while you load

Hand E.skeleton.while() the container, the promise and the shape. It resolves with the promise's value once the skeleton has gone, so you render into a clean container.

const users = await E.skeleton.while('#users', H.get('/api/users'), {type: 'list', count: 4});
$('#users').html(users.map(renderUser).join(''));

Step 3 - Handle failure

If the promise rejects, the skeleton is removed - whatever was in the container before comes back - and the error is rethrown for you to catch.

try {
    const users = await E.skeleton.while('#users', H.get('/api/users'), {type: 'list'});
    $('#users').html(users.map(renderUser).join(''));
} catch (err) {
    E.toast('Could not load users', {type: 'danger'});
}

Want to drive it yourself? E.skeleton() returns a handle: remove() restores the old content, replace(html) swaps in new content.

const sk = E.skeleton('#users', {type: 'list'});
const users = await H.get('/api/users');
sk.replace(users.map(renderUser).join(''));

Press Load: a pretend request takes a moment and the cards swap in where the placeholders were. The skeleton card has the same frame, padding and 16:9 image as a real .card.

$('#demo-cards-load').on('click', async () => {
    const posts = await E.skeleton.while('#demo-cards', pretendLoad(POSTS), {type: 'card', count: 3});
    $('#demo-cards').html(posts.map(renderPost).join(''));
});

Load fills the list. Load and fail rejects instead: the skeleton goes, the list you had comes back untouched, and the error reaches your catch.

try {
    const people = await E.skeleton.while('#demo-list', pretendLoad(PEOPLE, fail), {type: 'list', count: 4});
    $('#demo-list').html(renderPeople(people));
} catch (err) {
    E.toast(err.message, {type: 'danger'});   // the old list is back already
}

T.create(sel, {loadingSkeleton: true}) draws skeleton rows under the real header until the first setData() or addRow(). setLoading(true) brings them back for a reload. Pass a number instead of true for that many rows.

const table = T.create('#demo-table', {
    columns: ['name', 'role', 'city'].map((key) => ({key, title: _.capitalize(key)})),
    loadingSkeleton: true,
    pageSize: 5
});
table.setData(await H.get('/api/team'));

$('#demo-table-reload').on('click', async () => {
    table.setLoading(true);
    table.setData(await H.get('/api/team'));
});

The same call with a different type. Untick Animate for animate: false, a still tint with no sweep.

Current call: E.skeleton('#demo-types', {type: 'text', lines: 4});

No JavaScript needed. Put the shapes in your markup - server-rendered pages can ship them in the first paint - and swap the content in when it is ready.

<div class="skeleton skeleton-circle skeleton-lg"></div>
<div class="skeleton skeleton-heading"></div>
<div class="skeleton-lines">
    <div class="skeleton skeleton-text"></div>
    <div class="skeleton skeleton-text"></div>
    <div class="skeleton skeleton-text"></div>   <!-- the last line runs short -->
</div>
<span class="skeleton skeleton-button"></span>
<div class="skeleton skeleton-image skeleton-ratio-4x3"></div>

Mark containers with data-skeleton="type" and data-skeleton-* options, then call E.skeleton.scan() once. Take one away with E.skeleton.remove(el) or the handle's replace().

<div id="inbox" data-skeleton="list" data-skeleton-count="2" data-skeleton-avatar="false"></div>

<script>
    E.skeleton.scan();
    H.get('/api/inbox').then((mail) => E.skeleton.get('#inbox').replace(renderMail(mail)));
</script>

• The container gets aria-busy="true" while the skeleton is up and "false" after.
• A visually hidden role="status" (aria-live="polite") says "Loading..." - change it with label.
• The shapes carry aria-hidden="true": a screen reader hears one status, not forty grey boxes.
• Under prefers-reduced-motion: reduce the sweep is switched off and the still tint stays.

The tint is the theme's text colour mixed 10% into its surface, so it follows every theme. Override it with --dm-skeleton-bg, the sweep with --dm-skeleton-shine and its speed with --dm-skeleton-duration.

Methods