Skip to content

About

Loading placeholders that hold the shape of your content, then hand over to it. Native Web Components with a React adapter.

Topics

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Dotquilt

Dotquilt

Loading states that hand over.
Skeleton loaders that hold the shape of your content, then become it.

Website · Docs · Components · Examples · Playground

npm: dotquilt npm: @dotquilt/react Quality License: MIT Web Components React 19


A revenue screen loading: its figures take shape in square marks, a chart line draws from a field of dots, and the table rows settle, then everything hands over to the real content.

Dotquilt is a set of loading placeholders made of small marks. When your data arrives, the marks don't vanish: they travel to its real shape. Each skeleton line grows or shrinks to the length of your text, a number's marks take the shape of its digits, and a chart's marks glide onto your line. Then the content wipes in as they leave, in about a second.

  • Native Web Components with no runtime dependencies, for any framework or none.
  • A React 19 adapter with server rendering and clean hydration.
  • Accessible by default. Pending content is inert and hidden from screen readers, focus is kept, reduced motion swaps content in at once, and forced-colours mode shows a clear outline.
  • Calm. The idle glow stops after four seconds. delay and min-display keep fast loads from flickering.
  • Strict CSP. No inline style attributes: allow the stylesheets with a nonce or hashes, or serve them as files.
  • Only what you use. Each component has its own entry point and registers itself on demand.

Note

Dotquilt is in alpha (0.x): the API may still change before 1.0. Feedback and issues are very welcome.

Install

npm install dotquilt

For React:

npm install @dotquilt/react dotquilt

Quick start

Wrap the content that loads in a region, give it a placeholder in its shape, and set it ready when the data arrives.

<dotquilt-region state="pending" aria-label="Revenue">
  <dotquilt-skeleton-text slot="placeholder" lines="3"></dotquilt-skeleton-text>
  <div id="revenue"></div>
</dotquilt-region>

<script type="module">
  import { registerLoadingRegion } from 'dotquilt/region';
  import { registerSkeletonText } from 'dotquilt/skeleton';

  registerLoadingRegion();
  registerSkeletonText();

  const region = document.querySelector('dotquilt-region');
  const data = await fetch('/api/revenue').then((response) => response.json());
  document.querySelector('#revenue').textContent = data.summary;
  region.update({ state: 'ready' });
</script>

The same in React:

'use client';
import { LoadingRegion, SkeletonText } from '@dotquilt/react';

export function Summary({ data }: { data: Revenue | null }) {
  return (
    <LoadingRegion
      aria-label="Revenue"
      state={data ? 'ready' : 'pending'}
      placeholder={<SkeletonText lines={3} />}
    >
      {data && <RevenueCard data={data} />}
    </LoadingRegion>
  );
}

Your app owns the request. The region only needs to know whether the data is pending, refreshing (the content stays visible and usable) or ready.

Components

Six loaders handing over one after another: a chart line, a revenue figure, a profile, a table, a reply and an activity feed.
Component Element Use it for
LoadingRegion <dotquilt-region> Wraps content: a placeholder while pending, a refresh cue while refreshing, a handoff when ready
Skeleton <dotquilt-skeleton-block>, -line, -circle, -text Images, lines, avatars and paragraphs
TextLoader <dotquilt-text-loader> Numbers and short labels that take shape in marks
ChartLoader <dotquilt-chart-loader> Line, bar and scatter charts: marks glide onto your real data
TableLoader <dotquilt-table-loader> Tables: each cell's marks gather into its text
TypingDots <dotquilt-typing-dots> A reply that is being written

Every loader comes in dot, dash and square marks, in light and dark, themed with --dotquilt-* custom properties. Try them all in the playground.

Guides

Examples

  • Examples gallery: a dashboard and recipes for real product screens, each with its code.
  • examples/next: a Next.js App Router project with server rendering, hydration and a client-side navigation.

Repository

Path What it is
packages/core dotquilt: the native Web Components runtime, framework-free
packages/react @dotquilt/react: the React 19 adapter, with server rendering
apps/site dotquilt.dev: docs, examples and the playground (Astro + Starlight)
examples/next A Next.js App Router example
design The design spec and tokens

Contributing

Issues and pull requests are welcome. CONTRIBUTING.md covers setup, tests and how changes are made.

License

MIT

About

Loading placeholders that hold the shape of your content, then hand over to it. Native Web Components with a React adapter.

Topics

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages