kskeleton

Skeleton loading overlays for Svelte 5. Mark an element, and KSkeleton draws a shimmering placeholder on top of it that matches its real size, position and border radius. There is no separate skeleton markup to write or keep in sync.

Status: early (0.x). Each marked element gets one placeholder rectangle. Automatic shapes for a component's inner structure (avatar, text lines, buttons) are not built yet. See Limitations.

Install

npm install kskeleton

Requires Svelte 5.

Usage

Wrap the part of your page that has a loading state in Wrapper, and mark the elements you want skeletonized with use:kskeleton.

<script lang="ts">
	import { Wrapper, kskeleton } from 'kskeleton';

	let loading = $state(true);
</script>

<Wrapper {loading}>
	<div use:kskeleton class="card">
		<h2>Title</h2>
		<p>Content that is still loading</p>
	</div>

	<button onclick={() => (loading = !loading)}>Toggle</button>
</Wrapper>

While loading is true, the marked element is covered by a shimmering placeholder. When it becomes false, the placeholder is removed.

How it works

Wrapper holds the shared loading state. Every element marked with use:kskeleton registers with the nearest Wrapper above it. For each registered element that should show a skeleton, KSkeleton measures it with getBoundingClientRect(), copies its border radius and shadow, and places an overlay on top. The overlay follows the element when it resizes, moves, or when the page or a scroll container scrolls.

API

<Wrapper loading={boolean}>

| Prop | Type | Default | Description | | --- | --- | --- | --- | | loading | boolean | false | Whether marked elements inside show their skeleton. |

You can use several Wrappers on one page, each with its own loading state, for regions that load independently. An element registers with the closest Wrapper above it.

use:kskeleton

| Usage | Behavior | | --- | --- | | use:kskeleton | Follows the Wrapper's loading state. | | use:kskeleton={false} | Never shows a skeleton, whatever the Wrapper says. | | use:kskeleton={true} | Always shows a skeleton, whatever the Wrapper says. | | use:kskeleton={someState} | Follows someState, and updates when it changes. |

use:kskeleton must be used inside a Wrapper. Outside one, it throws an error.

Theming

Set these CSS custom properties anywhere above the overlay (for example on :root, or on .dark) to change its look:

| Variable | Default | Description | | --- | --- | --- | | --kskeleton-base | #e2e2e2 | Base color of the placeholder. | | --kskeleton-highlight | rgba(255, 255, 255, 0.5) | Color of the moving highlight. | | --kskeleton-duration | 1.5s | Duration of one shimmer sweep. |

:root {
	--kskeleton-base: #2a2a2a;
	--kskeleton-highlight: rgba(255, 255, 255, 0.08);
}

Overlays have the class kskeleton, so you can also target them directly.

Accessibility

• While an element shows a skeleton, it gets aria-busy="true" and inert, so keyboard users can't focus controls hidden under the overlay and screen readers don't read half-loaded content. Both are removed when loading ends.
• If the user prefers reduced motion (prefers-reduced-motion: reduce), the shimmer animation is turned off and the placeholder is a flat block.

Limitations

• One rectangle per marked element. A card becomes a single block, not separate shapes for its avatar, text and buttons. Mark the smaller elements individually if you want more detail.
• Server-side rendering. Overlays are created in the browser, after hydration. A page rendered with loading = true on the server briefly shows the real content before the skeleton appears. If that matters, render with loading = false on the server and set it to true in onMount.
• inert hides everything inside the element while loading. Anything in it that must stay usable during loading (for example a cancel button) should be outside the marked element.
• Overlays live in <body>. They are not clipped by ancestors with overflow: hidden, and they don't participate in your stacking contexts.
• Third-party components. You can mark any element you render, but you can't mark elements inside a component you don't control.

Development

npm install
npm run dev      # demo app
npm run check    # type-check
npm run prepack  # build the package into dist/ and lint it with publint

License

MIT