# Introduction > What Dotquilt is, how its skeleton loaders work, and how a loading region hands over from placeholder to your content. Dotquilt is a set of skeleton loaders (loading placeholders) drawn from small marks. While your data loads, the marks hold the shape of what is coming. When it arrives, they fade out as your content rises into place. ## What is a skeleton loader? A skeleton loader, or skeleton screen, is a placeholder in the shape of the content that is on its way: lines where text will be, a block for an image, a circle for an avatar. It shows that something is loading and where it will appear, and it keeps that space, so the page doesn't jump when the content arrives. A spinner only says that something is happening. Dotquilt's skeleton loaders are made of small marks. When your data arrives, the marks move to your content's real shape, then hand over to it. For when to use a skeleton and when a spinner or a progress bar is better, see [Skeleton loader or spinner?](/docs/guides/skeleton-or-spinner/). ## How it works Every loader sits inside a **loading region**. The region decides when to switch; the loader only draws. - **Pending:** the region shows its placeholder and keeps your content hidden from people and assistive technology. - **Ready:** the region hands over. The marks travel to your content's real shape (each line's length, the image, the avatar), then your content wipes in as they leave, in about a second. - **Refreshing:** your content stays visible and usable while new data loads. Your application owns the data, the request and the state. Dotquilt owns only the decoration and the handoff. ## The components | Component | Holds the place of | | --- | --- | | SkeletonBlock, SkeletonLine, SkeletonCircle, SkeletonText | images, text lines, avatars and paragraphs | | TextLoader | a number or short label | | ChartLoader | a chart | | TableLoader | a table | | TypingDots | a reply that is being written | | LoadingRegion | the area that switches from placeholder to content | ## Works everywhere The components are native web components, so they work in plain HTML and in any framework. A thin React adapter adds server rendering and typed props. Reduced motion, forced colours and keyboard focus are handled for you. Source: https://dotquilt.dev/docs/ --- # Installation > Install dotquilt with npm or Bun, add @dotquilt/react for React 19, and register only the components you use. ## Install **npm** ```sh npm install dotquilt ``` **bun** ```sh bun add dotquilt ``` For React, add the adapter too: ```sh npm install @dotquilt/react ``` ## Register the components Each component has its own entry point, so you only ship what you use. Register them once, before they appear on the page. **Native** ```ts import { registerLoadingRegion } from 'dotquilt/region'; import { registerSkeletonText } from 'dotquilt/skeleton'; registerLoadingRegion(); registerSkeletonText(); ``` **React** The React components register themselves. Import them from the adapter: ```tsx import { LoadingRegion, SkeletonText } from '@dotquilt/react'; ``` To register every component at once, call `registerAll()` from `dotquilt/register-all`. `LoadingRegion` loads its reveal animation on its own, the first time a region shows its placeholder, so it doesn't weigh on the first page load. Bundlers such as Vite and webpack split it into its own file. If the data arrives before that file has loaded, that one handover uses the simpler dissolve. ## Show a placeholder **Native** ```html
…your content…
``` When the data arrives, fill in your content and set the state: ```ts const region = document.querySelector('dotquilt-region'); region?.update({ state: 'ready' }); ``` **React** ```tsx } >
…your content…
``` Give each region a label, so assistive technology can name what is loading. For a complete component with a real request, errors and stale answers, see the usage example on the [Skeleton](/docs/components/skeleton/#usage) page. Source: https://dotquilt.dev/docs/installation/ --- # Set up with an AI assistant > One prompt for your coding assistant that reads your project, asks a few questions, and adds Dotquilt one place at a time. Paste one prompt into your coding assistant, such as Claude Code, Codex, Cursor or GitHub Copilot. It reads your project, shows you every place that waits for content and asks a few questions, then adds Dotquilt one place at a time and checks its work. ## What it does 1. **Learns Dotquilt** from these docs, as Markdown ([llms-full.txt](/llms-full.txt)), rather than from memory. 2. **Reads your project:** the framework and how it renders, how data loads, your styles and dark mode, any Content Security Policy, and every place that waits for content (spinners, hand-made skeletons, "Loading…" text, Suspense fallbacks). It leaves button spinners and upload progress alone. 3. **Shows you what it found and asks** only what the code can't tell it: which places to convert first, whether to replace an existing skeleton library, marks and colours, timing for fast responses. It waits for your answers before changing any file. 4. **Adds Dotquilt in order:** install, one-time setup (theme, CSP), then the most-seen place end to end, then the rest one at a time. Each placeholder gets the content's shape and size, and your data loading stays as it is: it only reads whether the data is pending, refreshing or ready. 5. **Checks its work:** types, lint, tests and build, then each place in the browser, in light and dark, on a narrow window and with reduced motion. It ends with a report of what changed and how to undo it. ## Use it - **Paste it** into a new chat in your assistant's agent mode, at the root of your project. Review the plan it proposes before you answer its questions. - **Or point to it.** If your assistant can read web pages, one line is enough: ```text Read https://dotquilt.dev/setup-prompt.md and follow it to add Dotquilt to this project. ``` It works with any framework: React 19 gets the React components, and everything else (Vue, Svelte, Angular, plain HTML, or an older React) gets the native elements. ## The prompt ```md title="setup-prompt.md" # Add Dotquilt loading states to this project You are adding Dotquilt to this codebase. Dotquilt is a set of loading placeholders that hold the shape of the content while it loads, then hand over to it: when the data arrives, the placeholder's marks travel to the content's real shape, and the content wipes in as they leave. Work in four phases. **Change no files until the user has answered your questions at the end of phase 2.** - `dotquilt`: native Web Components with no runtime dependencies, for any framework or none. - `@dotquilt/react`: React 19 components with server rendering. Peer dependencies: `react` and `react-dom` 19. ## Phase 1: Learn Dotquilt Read the documentation first: https://dotquilt.dev/llms-full.txt has every page as Markdown (https://dotquilt.dev/llms.txt is the index). Prefer it over memory: Dotquilt is new, and your training data may not know it. You need the exact text, so if your web tool summarises pages, download the file instead (for example with `curl`). If you can't fetch URLs at all, use the reference at the end of this prompt, and once the packages are installed, their TypeScript types. ## Phase 2: Analyse the project, then ask Read the code; don't guess. Find: 1. **Stack.** Framework and version (Next.js App Router or Pages Router, Remix or React Router, Vite with React, Astro, Vue, Svelte, Angular, plain HTML), React version, TypeScript, the package manager (from the lockfile), and the workspace layout in a monorepo. 2. **Rendering.** Where code runs: server components, server rendering, static export or a client-only app. Where the `'use client'` boundaries are. 3. **Data loading.** How data arrives: `fetch` in effects, TanStack Query, SWR, Apollo or urql, RTK Query, server actions, route loaders, Suspense. Which states each one exposes: the first load, a background refetch, pagination that keeps the previous page, errors. 4. **Every place that waits for content.** Search for `isLoading`, `isPending`, `isFetching`, `loading`, `status === 'loading'`, Suspense `fallback`, `loading.tsx` or `loading.js`, `Skeleton`, `Spinner`, `Loader`, `animate-pulse`, `shimmer`, "Loading…" text, placeholder libraries (react-loading-skeleton, MUI, shadcn/ui, Chakra or Ant Design skeletons) and "is typing" indicators. For each: the file and line, what content it stands in for (a paragraph, a list, a card, an avatar, an image, a number, a table, a chart, a chat reply), its size, and how often people see it. 5. **What to leave alone.** Spinners in buttons and form submissions, upload progress and route-change indicators show that an action is running, not the shape of content. They stay as they are. 6. **Styling and theme.** The CSS approach (Tailwind, CSS Modules, CSS-in-JS, plain CSS), the design tokens or brand colours, and how dark mode works (a media query, a class or a data attribute). 7. **Constraints.** A Content Security Policy (in headers, middleware or a meta tag): does `style-src` allow inline styles, use a nonce, or hashes? Tests that cover loading states (unit, component, end-to-end, visual snapshots). 8. **Gaps.** Places that never leave their loading state when a request fails, and places with no error message. Note them; fixing them means changing data code, so they are follow-ups unless the user asks. Then reply with: - **Findings:** the stack in a few lines, and a table of the waiting places: `# | file | stands in for | today | data source | proposed placeholder | priority`. - **Plan:** the steps of phase 3, filled in for this project. - **Questions:** only what the code didn't answer, each with your recommended default. Typical ones: 1. Which places: all of them, or the highest-priority few first? 2. Replace an existing skeleton library, or leave it where it is? 3. Marks: `dot` (the default), `dash` (suits text lines and table rows) or `square` (crisp at small sizes)? 4. Colours: Dotquilt's neutral slate with a teal glow, or the app's own tokens (name the ones you'd use)? 5. Fast responses: skip the placeholder for answers under about 150 ms (`delay`), and keep a shown one for at least about 500 ms (`minDisplay`)? 6. The nonce source, if a Content Security Policy needs one. 7. React below 19: upgrade React, or use the native elements? **Stop here and wait for the answers.** ## Phase 3: Implement, in this order 1. **Install** with the project's package manager: `dotquilt`, plus `@dotquilt/react` for React 19, version 0.1.2 or later (upgrade an older install). Check the installed versions and peer dependencies. 2. **Set up once, globally.** - **Theme**, if the user wants the app's colours: set `--dotquilt-color` (the resting marks) and `--dotquilt-accent-color` (the glow and the chart's handoff) in global CSS, for light and dark, from the app's tokens, under the app's own dark-mode selector. - **Dark mode:** Dotquilt's default colours use `light-dark()`, which follows the page's `color-scheme`. If the app has a dark mode but never sets `color-scheme` (common when dark mode is only a media query or a class), set it to match (`color-scheme: light dark`, or `dark` under the app's dark selector), or set both colour properties for each mode as above. Otherwise the marks stay light in dark mode. If the theme switches with a class while the page is open, call `refreshStyles(document)` from `dotquilt` after the switch: ChartLoader and TableLoader draw on a canvas and read their colours once. - **Content Security Policy**, if styles need a nonce or hashes: pass the same `stylePolicy` to every Dotquilt component (`{ mode: 'inline', nonce }`, or `{ mode: 'external', href }` with the stylesheets the package ships). A small wrapper that supplies it is fine. - **Native elements only:** call each `register…()` once in the client entry, before the elements are used. The React components register themselves. 3. **Convert the highest-priority place first,** end to end, and check it in the browser before repeating the pattern. 4. **Convert the rest, one place at a time,** in priority order. For each: - **Wrap only the part that loads** in a `LoadingRegion` (``) with an `aria-label` naming what loads. Keep headings, card frames, toolbars and table headers outside the region: they are already there and should stay still. A `TextLoader` holds a single value and is its own region, with no wrapper. - **Map the existing state; don't change how data is fetched:** - the first load, with nothing to show yet: `state="pending"`; - a newer copy of data already on screen (a background refetch, the next page while the previous one stays, a refresh button): `state="refreshing"`, which keeps the content visible and usable; - data, an empty result or an error: `state="ready"`. For an error, also pass `timing={{ duration: 0 }}` so the app's error message replaces the placeholder at once. - `cycle`: a string that names the current request (an id, the query key, a page number), so a stale answer can't settle a newer one. - **Pick the placeholder by the content's shape, and give it the content's size,** so nothing moves when the content arrives: | Content | Placeholder | | --- | --- | | Paragraphs, lists of text | `SkeletonText` with about as many `lines` as the text, or one `SkeletonLine` per line with widths like the real ones | | An avatar | `SkeletonCircle` at the avatar's size | | An image, media or a card | `SkeletonBlock` at the content's height or aspect ratio | | A number or a short label | `TextLoader` with a `mask` in the value's shape, such as `$00,000` | | A line, bar or scatter chart | `ChartLoader` with its `variant`, at the chart's height, and a `targetProvider` that returns where the real line, bars or points will be | | A table's rows | `TableLoader` with the real table's `rows`, `rowHeight` and `columns` (`text`, `number`, `badge` or `date`, with width shares; `number` cells end-align, so use it only for end-aligned figures) | | A reply being written | `TypingDots` in the reply bubble | Measure the real content in the browser and match it: give `SkeletonText` the text's line height (a `gap` and `margin-block` from `1lh`, as the Skeleton page shows). - **Tables:** a region can't sit inside a `` (the HTML parser moves it out, and hydration breaks), and `TableLoader` draws rows, not a header. To keep the column headers still while only the rows load, put the header in its own `
` above the region, give both tables the same `` widths with `table-layout: fixed`, and name the columns for screen readers in the table inside the region with a visually hidden `` (the project's `sr-only` or visually-hidden class): the handoff draws no marks for text that can't be seen. For a table built from CSS grid, keep the header row outside the region. Don't wrap the whole table, header included, in one region: the header would wipe in with the rows. - **Refreshing regions** draw a thin row of marks just above their top edge, across their full width. Leave room above a region that sits right under a toolbar or button (a margin, or `--dotquilt-refresh-gap`), so the row doesn't cross it. - **TextLoader** takes its value as one string child (`{formatted}`, not `$` followed by `{value}`), and its `aria-label` names the value. - **Share a placeholder** that appears twice, such as in a region and in a route's `loading.tsx`, as one small component, so both stay the same shape. - **Remove what it replaces** for that place: the spinner or skeleton markup, and CSS, imports or packages left unused, if the user agreed. 5. **Follow the framework's rules.** - **Next.js App Router:** the components are client components that also render on the server. Keep the state in a client component of your own. Render the same `state` on the server and in the first client render (no `typeof window` branches), and never load Dotquilt with `dynamic(..., { ssr: false })`. Functions such as `targetProvider` can't cross from a Server Component, so keep them in client components. - **Suspense fallbacks and `loading.tsx`:** a placeholder can be the fallback on its own, without a region. On its own it is decoration, hidden from assistive technology, so keep the page's own words nearby if the wait matters. - **Vue, Svelte, Angular or plain HTML:** use the native elements. Tell the framework they are custom elements (Vue's `compilerOptions.isCustomElement`, Angular's `CUSTOM_ELEMENTS_SCHEMA`), and set `state` as an attribute or call `region.update({ state, cycle })`. - **React below 19:** the adapter needs React 19. Use the native elements through refs, or upgrade if the user chose to. - **Import only what a page uses:** `@dotquilt/react` (or a single entry such as `@dotquilt/react/region`); for native elements, `dotquilt/region`, `dotquilt/skeleton`, `dotquilt/text`, `dotquilt/chart`, `dotquilt/table` and `dotquilt/typing`. 6. **Keep it accessible.** Every region has an `aria-label`. Keep the app's own messages: errors in `role="alert"`, and a `role="status"` line outside the region where the wait matters. Don't add `aria-busy` or your own reduced-motion checks around Dotquilt: the region already keeps pending content out of reach and follows the visitor's motion settings. ## Phase 4: Verify, then report 1. Run the project's type check, linter, tests and build. Fix what the change broke. Update snapshots only where a loading state changed on purpose, and say which. 2. Run the app and check each converted place: the placeholder shows at the content's size, the content arrives without the layout jumping, the handoff plays, and an error swaps in at once. Check light and dark, a narrow window, and reduced motion (the content then swaps in without the animation). 3. With server rendering: the first HTML already holds the placeholder, and the browser console shows no hydration warnings. 4. Report: what changed in each place (file, before and after), anything skipped and why, suggested follow-ups, and how to undo it (the packages and files touched). ## Rules - **Change presentation only.** Read the data layer's state; don't change requests, query keys, caching, retries or error handling. - **Leave action indicators alone:** button spinners, submit and upload progress, route-change bars. - **Follow the project's conventions** for file layout, naming, formatting and component patterns. Don't add a state library or rewrite components. - **One place at a time;** the project builds after each. - **Don't invent APIs.** If unsure, read the docs or the package's types. ## Reference Use this only if you can't read the docs. - **React:** `} delay={150} minDisplay={500} timing={{ duration: 0 }}>{content}`. - **Skeletons:** `SkeletonText` (`lines`), `SkeletonLine`, `SkeletonCircle`, `SkeletonBlock`; size them with CSS like any element. - **TextLoader:** `{formatted}`, with the value as one string. The character effect covers printable ASCII on one line; other text falls back to a plain field of marks. - **ChartLoader:** ` data ? { kind: 'line', points: [{ x, y }, …], baseline: height } : null} style={{ height: 160 }} />`; `kind: 'bar'` takes `bars` (rectangles) and a `baseline`, `kind: 'scatter'` takes `points`. - **TableLoader:** ``. - **TypingDots:** ``. - **Native:** `…content…`, then `region.update({ state: 'ready', cycle })`. - **States:** `pending` shows the placeholder and keeps the content hidden and inert; `refreshing` keeps the content visible with a thin row of marks above it; `ready` hands over in about a second. - **Every component:** `mark` (`dot`, `dash`, `square`), `motion` (`system` or `paused`), `stylePolicy`. - **Theme properties:** `--dotquilt-color`, `--dotquilt-accent-color`, `--dotquilt-dot-size`, `--dotquilt-dot-gap`, `--dotquilt-radius`, `--dotquilt-refresh-gap`. The defaults use `light-dark()`, so the page's `color-scheme` decides light or dark. ``` Source: https://dotquilt.dev/docs/ai-setup/ --- # Theming > Colours, mark size and spacing, light and dark, and the alternative marks. Dotquilt's marks use a slate close to your text colour and a soft teal glow, so they sit inside any product without imposing a brand colour. Every part of that is a CSS custom property you can set on any element: it applies to every loader inside. ```css .dashboard { --dotquilt-color: #5b6b62; --dotquilt-accent-color: #3f7f86; --dotquilt-dot-size: 5px; --dotquilt-dot-gap: 5px; } ``` ## Custom properties | Property | Default | Changes | | --- | --- | --- | | `--dotquilt-color` | `light-dark(#6E7889, #A3AFC2)` | the resting marks | | `--dotquilt-accent-color` | `light-dark(#4F8F93, #8DC4C5)` | the idle glow and chart handoff | | `--dotquilt-dot-size` | `4.4px` (TypingDots `8px`) | each dot's diameter | | `--dotquilt-dot-gap` | `4.6px` (TypingDots `6px`) | the space between dots | | `--dotquilt-radius` | `.375rem` | a SkeletonBlock's corners | | `--dotquilt-refresh-gap` | `6px` | how far above a refreshing region its row of marks sits | ## Light and dark The default colours follow the page's `color-scheme` (they use `light-dark()`). If your page never sets one, they stay light, even when your own styles turn dark with a `prefers-color-scheme` media query. Declare both: ```css :root { color-scheme: light dark; } ``` If your dark theme is a class rather than the system setting, set `color-scheme: dark` along with it: ```css .theme-dark { color-scheme: dark; } ``` ChartLoader and TableLoader draw on a canvas and read their colours once. When you switch themes with a class, tell them to read again: ```ts import { refreshStyles } from 'dotquilt'; document.documentElement.classList.toggle('theme-dark'); refreshStyles(document); ``` ## Marks Every loader takes a `mark`: `dot` (the default), `square` or `dash`. The positions and motion stay the same; only the shape and spacing change. | Mark | Shape | Spacing | Suits | | --- | --- | --- | --- | | `dot` | 4.4 px circle | 9 px | everything | | `square` | 4 × 4 px, softly rounded | 8.5 px | small sizes, and a pixel font in TextLoader | | `dash` | 9.4 × 3.4 px, round ends | 13 × 9.5 px | text lines and table rows | Squares and dashes have a fixed size, so the size and gap properties change dots only. On a chart, dashes follow the line: they turn with it as it rises and falls, and lie level in the shaded area below. ## Forced colours In Windows high-contrast mode the marks are replaced by a dotted outline in the system text colour, so placeholders stay visible without decoration. Source: https://dotquilt.dev/docs/theming/ --- # ChartLoader > A chart loading skeleton for line, bar and scatter charts: a field of marks that glides onto your real data when it arrives. ChartLoader is Dotquilt's chart loading skeleton: it holds the place of a line, bar or scatter chart. A faint field of marks carries a slow ridge and a drifting glow. When the data arrives, the marks glide onto your real line, turning teal, and then your chart draws in. ## Usage Put a ChartLoader in a region's placeholder slot, sized like the chart it stands in for. Give it a **target provider**: a function that says where your real line will be, in the loader's own size. The marks glide onto it during the handoff. **React** ```tsx title="RevenueChart.tsx" 'use client'; import { ChartLoader, LoadingRegion } from '@dotquilt/react'; import type { TargetProvider } from 'dotquilt/chart'; import { useEffect, useState } from 'react'; import { linePath, linePoints } from './data'; async function fetchRevenue( year: number, signal: AbortSignal, ): Promise { const response = await fetch(`/api/revenue/${year}`, { signal }); if (!response.ok) throw new Error(`Request failed: ${response.status}`); return response.json(); } type Result = | { status: 'loading' } | { status: 'done'; series: number[] } | { status: 'failed' }; export function RevenueChart({ year }: { year: number }) { const [result, setResult] = useState({ status: 'loading' }); useEffect(() => { const request = new AbortController(); setResult({ status: 'loading' }); fetchRevenue(year, request.signal) .then((series) => setResult({ status: 'done', series })) .catch(() => { if (!request.signal.aborted) setResult({ status: 'failed' }); }); return () => request.abort(); }, [year]); // Where the real line will be, in the loader's own size: the marks glide // onto it before the chart draws in. const target: TargetProvider = ({ width, height }) => result.status === 'done' ? { kind: 'line', points: linePoints(result.series, width, height), baseline: height, } : null; return ( } > {result.status === 'done' && ( )} {result.status === 'failed' && (

We couldn't load revenue. Try again later.

)}
); } export function Report() { return ; } ``` ```ts title="data.ts" // Shared by the docs examples and the live previews, so both draw the same. import type { Point } from 'dotquilt/chart'; import type { TableColumn } from 'dotquilt/table'; /** Monthly revenue, in thousands. */ export const revenue: readonly number[] = [32, 41, 38, 52, 47, 61, 58, 72]; /** Each value's place in a chart `width` × `height`, with headroom on top. */ export function linePoints( values: readonly number[], width: number, height: number, ): Point[] { const top = Math.max(...values) * 1.15; return values.map((value, i) => ({ x: (i / Math.max(1, values.length - 1)) * width, y: height - (value / top) * height, })); } /** An SVG path through the same points. */ export function linePath( values: readonly number[], width: number, height: number, ): string { return linePoints(values, width, height) .map(({ x, y }, i) => `${i ? 'L' : 'M'}${x.toFixed(1)} ${y.toFixed(1)}`) .join(' '); } export interface Invoice { customer: string; amount: string; status: string; due: string; } export const invoices: readonly Invoice[] = [ { customer: 'Northwind', amount: '$4,200', status: 'Paid', due: 'Nov 2' }, { customer: 'Acme Labs', amount: '$1,870', status: 'Open', due: 'Nov 14' }, { customer: 'Globex', amount: '$9,640', status: 'Overdue', due: 'Oct 28' }, { customer: 'Initech', amount: '$3,115', status: 'Paid', due: 'Nov 20' }, ]; /** The placeholder's columns: what each column holds, and its share of the width. */ export const invoiceColumns: readonly TableColumn[] = [ { kind: 'text', width: 2 }, { kind: 'number' }, { kind: 'badge' }, { kind: 'date' }, ]; ``` **Native** ```html title="index.html" ``` ```ts title="revenue.ts" import { type ChartLoader, registerChartLoader } from 'dotquilt/chart'; import { type LoadingRegion, registerLoadingRegion } from 'dotquilt/region'; import { linePath, linePoints } from './data'; registerLoadingRegion(); registerChartLoader(); const region = document.getElementById('revenue') as LoadingRegion | null; const chart = region?.querySelector('dotquilt-chart-loader') as ChartLoader; const line = region?.querySelector('path'); export async function showRevenue(year: number): Promise { if (!region || !line) return; const cycle = String(year); region.update({ state: 'pending', cycle }); try { const response = await fetch(`/api/revenue/${year}`); if (!response.ok) throw new Error(`Request failed: ${response.status}`); const series: number[] = await response.json(); if (region.cycle !== cycle) return; line.setAttribute('d', linePath(series, 320, 160)); // Where the real line will be, in the loader's own size: the marks glide // onto it before the chart draws in. chart.targetProvider = ({ width, height }) => ({ kind: 'line', points: linePoints(series, width, height), baseline: height, }); region.update({ state: 'ready' }); } catch { if (region.cycle !== cycle) return; region.querySelector('.chart-error')?.removeAttribute('hidden'); region.update({ state: 'ready', timing: { duration: 0 } }); } } void showRevenue(2026); ``` ```ts title="data.ts" // Shared by the docs examples and the live previews, so both draw the same. import type { Point } from 'dotquilt/chart'; import type { TableColumn } from 'dotquilt/table'; /** Monthly revenue, in thousands. */ export const revenue: readonly number[] = [32, 41, 38, 52, 47, 61, 58, 72]; /** Each value's place in a chart `width` × `height`, with headroom on top. */ export function linePoints( values: readonly number[], width: number, height: number, ): Point[] { const top = Math.max(...values) * 1.15; return values.map((value, i) => ({ x: (i / Math.max(1, values.length - 1)) * width, y: height - (value / top) * height, })); } /** An SVG path through the same points. */ export function linePath( values: readonly number[], width: number, height: number, ): string { return linePoints(values, width, height) .map(({ x, y }, i) => `${i ? 'L' : 'M'}${x.toFixed(1)} ${y.toFixed(1)}`) .join(' '); } export interface Invoice { customer: string; amount: string; status: string; due: string; } export const invoices: readonly Invoice[] = [ { customer: 'Northwind', amount: '$4,200', status: 'Paid', due: 'Nov 2' }, { customer: 'Acme Labs', amount: '$1,870', status: 'Open', due: 'Nov 14' }, { customer: 'Globex', amount: '$9,640', status: 'Overdue', due: 'Oct 28' }, { customer: 'Initech', amount: '$3,115', status: 'Paid', due: 'Nov 20' }, ]; /** The placeholder's columns: what each column holds, and its share of the width. */ export const invoiceColumns: readonly TableColumn[] = [ { kind: 'text', width: 2 }, { kind: 'number' }, { kind: 'badge' }, { kind: 'date' }, ]; ``` Without a target provider, or if it returns `null`, the chart fades in over the marks instead. ## Target geometry The provider receives the loader's `width` and `height` and returns one of these, in the same pixels: | `kind` | Fields | Use | | --- | --- | --- | | `line` | `points`, `baseline` | line and area charts | | `bar` | `bars` (rects), `baseline` | bar charts | | `scatter` | `points` | scatter plots | ## Options | Attribute | React | Type | Default | Description | | --- | --- | --- | --- | --- | | `variant` | `variant` | `line` \| `bar` \| `scatter` | `line` | The kind of chart it stands in for. | | | `targetProvider` | function | | Where the real chart is, for the handoff. | | `mark` | `mark` | `dot` \| `square` \| `dash` | `dot` | The shape of each mark. | | `speed` | `speed` | number | `1` | How fast the ridge and glow move. | | `pointer-response` | `pointerResponse` | `none` \| `lift` | `none` | `lift` lights the marks around the pointer while the placeholder shows, on devices with a fine pointer. | | `motion` | `motion` | `system` \| `paused` | `system` | `system` follows the visitor's reduced-motion setting; `paused` stills the field. | The chart sizes like a block: it fills its width and is 12rem tall unless you set a height. ## Animations Import alternatives from `dotquilt/animations/chart` and pass them as `animations`. | Phase | Default | Also available | | --- | --- | --- | | Idle | `ridge`: a soft line drifting through the field | `bars`, `scatter`: shapes for those chart types; `scan`: a band sweeps across the line; `terrain`: the field below the line is shaded like land; `cycle`: moves between line, bars and scatter | | Handoff | `morphWipe`: marks glide onto the line, then the chart draws in | | Each takes options, for example `scan({ bandWidth: 48 })`: | Animation | Options (default) | | --- | --- | | `ridge` | `amplitude` 0–0.4 (0.24), `highlightWidth` 20–180 px (90) | | `scan` | `amplitude` 0–0.4 (0.24), `bandWidth` 12–80 px (36), `trail` 40–240 px (160) | | `terrain` | `amplitude` 0–0.4 (0.24), `relief` 0.4–1.4 (1) | | `bars` | `sway` 0–0.12 (0.07) | | `scatter` | `radius` 6–24 px (13), `spread` 0.1–0.35 (0.24), `sway` 0–0.1 (0.045) | | `cycle` | `holdMs` 800–3200 (3200), `blendMs` 200–600 (460) | | `morphWipe` | `morphEnd` 0.55–0.95 (0.55), `wipeStart` 0.15–0.6 (0.48), `edge` 4–80 px (40) | Source: https://dotquilt.dev/docs/components/chart-loader/ --- # LoadingRegion > The area that switches from placeholder to content, with pending, refreshing and ready states, and owns the handoff between them. 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. ## States | 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. ## Usage **React** ```tsx title="ActivityFeed.tsx" 'use client'; import { LoadingRegion, SkeletonText } from '@dotquilt/react'; import { useCallback, useEffect, useRef, useState } from 'react'; async function fetchActivity(signal: AbortSignal): Promise { 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(null); const [refreshing, setRefreshing] = useState(false); const [failed, setFailed] = useState(false); const latest = useRef(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 (
} > {failed && items === null ? (

We couldn't load activity. Try again later.

) : (
    {items?.map((item) => (
  • {item}
  • ))}
)}
); } ``` **Native** ```html title="index.html"
    ``` ```ts title="activity.ts" import { type LoadingRegion, registerLoadingRegion } from 'dotquilt/region'; import { registerSkeletonText } from 'dotquilt/skeleton'; registerLoadingRegion(); registerSkeletonText(); const region = document.getElementById('activity') as LoadingRegion | null; const list = region?.querySelector('[data-items]'); const button = document.getElementById('refresh') as HTMLButtonElement | null; let requests = 0; async function load(): Promise { if (!region || !list) return; const cycle = `activity-${++requests}`; // The first load hides the feed; later ones keep it visible and usable. region.update({ state: list.children.length ? 'refreshing' : 'pending', cycle, }); try { const response = await fetch('/api/activity'); if (!response.ok) throw new Error(`Request failed: ${response.status}`); const items: string[] = await response.json(); if (region.cycle !== cycle) return; list.replaceChildren( ...items.map((item) => Object.assign(document.createElement('li'), { textContent: item }), ), ); region.update({ state: 'ready' }); } catch { if (region.cycle !== cycle) return; // A failed refresh keeps the feed you already have. if (!list.children.length) list.append( Object.assign(document.createElement('li'), { textContent: "We couldn't load activity. Try again later.", }), ); region.update({ state: 'ready', timing: { duration: 0 } }); } } button?.addEventListener('click', () => void load()); void load(); ``` ## Slots | 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 | ## Options | 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. | ## Events | 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. ## Accessibility - **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. Source: https://dotquilt.dev/docs/components/loading-region/ --- # Skeleton > Skeleton loaders for images, text lines, avatars and paragraphs, made of marks, as native Web Components or React components. 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. ## Usage 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. **React** ```tsx title="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 { 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({ 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 ( } > {result.status === 'done' && (

    {result.member.name}

    {result.member.role}

    {result.member.bio}

    )} {result.status === 'failed' && (

    We couldn't load this member. Try again later.

    )}
    ); } // Use it like any other component; it loads again whenever `id` changes. export function Team() { return ; } ``` **Native** ```html title="index.html"

    Team member

    ``` ```ts title="member.ts" import { type LoadingRegion, registerLoadingRegion } from 'dotquilt/region'; import { registerSkeletonCircle, registerSkeletonLine, } from 'dotquilt/skeleton'; registerLoadingRegion(); registerSkeletonCircle(); registerSkeletonLine(); const region = document.getElementById('member') as LoadingRegion | null; export async function showMember(id: string): Promise { if (!region) return; // Each request is a new cycle; the placeholder shows until it settles. region.update({ state: 'pending', cycle: id }); try { const response = await fetch(`/api/members/${id}`); if (!response.ok) throw new Error(`Request failed: ${response.status}`); const member: Record = await response.json(); // A newer request took over while this one was in flight. if (region.cycle !== id) return; for (const field of region.querySelectorAll('[data-field]')) field.textContent = member[field.dataset.field ?? ''] ?? ''; region.update({ state: 'ready' }); } catch { if (region.cycle !== id) return; const card = region.querySelector('article'); if (card) card.textContent = "We couldn't load this member. Try again later."; // An error replaces the placeholder at once, without the handoff. region.update({ state: 'ready', timing: { duration: 0 } }); } } void showMember('ada'); ``` ### Matching your text's line height 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: ```css .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. ## Elements | Element | React | Use | | --- | --- | --- | | `` | `SkeletonBlock` | images, charts and other rectangles | | `` | `SkeletonLine` | one line of text | | `` | `SkeletonCircle` | avatars and icons | | `` | `SkeletonText` | a paragraph of lines | ## Options | 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`). ## Animations 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) | ## Colours The marks use a slate that sits inside any app, with a soft teal glow. Change them with custom properties: ```css .profile { --dotquilt-color: #627467; --dotquilt-accent-color: #3f7f86; } ``` Source: https://dotquilt.dev/docs/components/skeleton/ --- # TableLoader > A table skeleton loader: rows of marks shaped like your columns that gather into each cell's real text when the data arrives. TableLoader is Dotquilt's table skeleton loader: it holds the place of a table. Each cell shows a short bar of marks shaped like what the column holds, with a glow drifting across. When the data arrives, each cell's marks gather into the text in its place, then the rows wipe in as the marks leave. ## Usage Describe the columns and set how many rows to show. The handoff reads your real table, so it needs nothing else. **React** ```tsx title="InvoiceTable.tsx" 'use client'; import { LoadingRegion, TableLoader } from '@dotquilt/react'; import { useEffect, useState } from 'react'; import { type Invoice, invoiceColumns } from './data'; async function fetchInvoices(signal: AbortSignal): Promise { const response = await fetch('/api/invoices', { signal }); if (!response.ok) throw new Error(`Request failed: ${response.status}`); return response.json(); } export function InvoiceTable() { const [invoices, setInvoices] = useState(null); const [failed, setFailed] = useState(false); useEffect(() => { const request = new AbortController(); fetchInvoices(request.signal) .then(setInvoices) .catch(() => { if (!request.signal.aborted) setFailed(true); }); return () => request.abort(); }, []); // The handoff reads the real table: each cell's marks become its text. const ready = failed || invoices !== null; return ( } > {failed ? (

    We couldn't load invoices. Try again later.

    ) : (
    {invoices?.map((invoice) => ( ))}
    Customer Amount Status Due
    {invoice.customer} {invoice.amount} {invoice.status} {invoice.due}
    )} ); } ``` ```ts title="data.ts" // Shared by the docs examples and the live previews, so both draw the same. import type { Point } from 'dotquilt/chart'; import type { TableColumn } from 'dotquilt/table'; /** Monthly revenue, in thousands. */ export const revenue: readonly number[] = [32, 41, 38, 52, 47, 61, 58, 72]; /** Each value's place in a chart `width` × `height`, with headroom on top. */ export function linePoints( values: readonly number[], width: number, height: number, ): Point[] { const top = Math.max(...values) * 1.15; return values.map((value, i) => ({ x: (i / Math.max(1, values.length - 1)) * width, y: height - (value / top) * height, })); } /** An SVG path through the same points. */ export function linePath( values: readonly number[], width: number, height: number, ): string { return linePoints(values, width, height) .map(({ x, y }, i) => `${i ? 'L' : 'M'}${x.toFixed(1)} ${y.toFixed(1)}`) .join(' '); } export interface Invoice { customer: string; amount: string; status: string; due: string; } export const invoices: readonly Invoice[] = [ { customer: 'Northwind', amount: '$4,200', status: 'Paid', due: 'Nov 2' }, { customer: 'Acme Labs', amount: '$1,870', status: 'Open', due: 'Nov 14' }, { customer: 'Globex', amount: '$9,640', status: 'Overdue', due: 'Oct 28' }, { customer: 'Initech', amount: '$3,115', status: 'Paid', due: 'Nov 20' }, ]; /** The placeholder's columns: what each column holds, and its share of the width. */ export const invoiceColumns: readonly TableColumn[] = [ { kind: 'text', width: 2 }, { kind: 'number' }, { kind: 'badge' }, { kind: 'date' }, ]; ``` **Native** ```html title="index.html"
    Customer Amount Status Due
    ``` ```ts title="invoices.ts" import { type LoadingRegion, registerLoadingRegion } from 'dotquilt/region'; import { registerTableLoader, type TableLoader } from 'dotquilt/table'; import { type Invoice, invoiceColumns } from './data'; registerLoadingRegion(); registerTableLoader(); const region = document.getElementById('invoices') as LoadingRegion | null; const table = region?.querySelector('dotquilt-table-loader') as TableLoader; const body = region?.querySelector('tbody'); // What each column holds, and its share of the width. table.columns = invoiceColumns; export async function showInvoices(): Promise { if (!region || !body) return; region.update({ state: 'pending', cycle: 'invoices' }); try { const response = await fetch('/api/invoices'); if (!response.ok) throw new Error(`Request failed: ${response.status}`); const invoices: Invoice[] = await response.json(); body.replaceChildren( ...invoices.map((invoice) => { const row = document.createElement('tr'); for (const value of [ invoice.customer, invoice.amount, invoice.status, invoice.due, ]) row.append( Object.assign(document.createElement('td'), { textContent: value }), ); return row; }), ); // The handoff reads the real table: each cell's marks become its text. region.update({ state: 'ready' }); } catch { const message = document.createElement('td'); message.colSpan = 4; message.textContent = "We couldn't load invoices. Try again later."; body.replaceChildren(document.createElement('tr')); body.rows[0]?.append(message); region.update({ state: 'ready', timing: { duration: 0 } }); } } void showInvoices(); ``` ```ts title="data.ts" // Shared by the docs examples and the live previews, so both draw the same. import type { Point } from 'dotquilt/chart'; import type { TableColumn } from 'dotquilt/table'; /** Monthly revenue, in thousands. */ export const revenue: readonly number[] = [32, 41, 38, 52, 47, 61, 58, 72]; /** Each value's place in a chart `width` × `height`, with headroom on top. */ export function linePoints( values: readonly number[], width: number, height: number, ): Point[] { const top = Math.max(...values) * 1.15; return values.map((value, i) => ({ x: (i / Math.max(1, values.length - 1)) * width, y: height - (value / top) * height, })); } /** An SVG path through the same points. */ export function linePath( values: readonly number[], width: number, height: number, ): string { return linePoints(values, width, height) .map(({ x, y }, i) => `${i ? 'L' : 'M'}${x.toFixed(1)} ${y.toFixed(1)}`) .join(' '); } export interface Invoice { customer: string; amount: string; status: string; due: string; } export const invoices: readonly Invoice[] = [ { customer: 'Northwind', amount: '$4,200', status: 'Paid', due: 'Nov 2' }, { customer: 'Acme Labs', amount: '$1,870', status: 'Open', due: 'Nov 14' }, { customer: 'Globex', amount: '$9,640', status: 'Overdue', due: 'Oct 28' }, { customer: 'Initech', amount: '$3,115', status: 'Paid', due: 'Nov 20' }, ]; /** The placeholder's columns: what each column holds, and its share of the width. */ export const invoiceColumns: readonly TableColumn[] = [ { kind: 'text', width: 2 }, { kind: 'number' }, { kind: 'badge' }, { kind: 'date' }, ]; ``` With a `targetProvider`, the table uses the `rows` handoff instead: each cell's marks form its characters, glyph by glyph, and the rows you pass as the region's **reveal targets** settle in one after another. ## Options | Attribute | React | Type | Default | Description | | --- | --- | --- | --- | --- | | `rows` | `rows` | number | `5` | How many rows to show, up to 100. | | `row-height` | `rowHeight` | number | `32` | Row height in pixels. | | | `columns` | `{ kind, width? }[]` | three text columns | What each column holds (`text`, `number`, `badge` or `date`) and its share of the width. Up to 20. | | `mark` | `mark` | `dot` \| `square` \| `dash` | `dot` | Dashes suit table rows well. | | `speed` | `speed` | number | `1` | How fast the glow moves. | | `pointer-response` | `pointerResponse` | `none` \| `lift` | `none` | `lift` lights the marks around the pointer while the placeholder shows, on devices with a fine pointer. | | `motion` | `motion` | `system` \| `paused` | `system` | `system` follows the visitor's reduced-motion setting; `paused` stills the field. | ## Animations Import alternatives from `dotquilt/animations/table` and pass them as `animations`. | Phase | Default | Also available | | --- | --- | --- | | Idle | `tableShimmer`: still bars under a drifting glow | `typeOn`: bars grow as if being typed | | Handoff | the marks gather into each cell's real text, then the rows wipe in | `rows` (with a `targetProvider`): cells form their characters and rows settle in 80 ms apart | | Animation | Options (default) | | --- | --- | | `tableShimmer`, `typeOn` | `cadenceMs` 250–1200 (600), `cellStyle`: `auto` (from the columns), `text`, `number`, `badge`, `date`, `badge-text` or `text-badge` | | `rows` | `staggerMs` 0–120 (80), `settlePx` 0–8 (5) | Source: https://dotquilt.dev/docs/components/table-loader/ --- # TextLoader > A loading placeholder for numbers, KPIs and short labels that scrambles while it loads, then takes the real value's shape and hands over to it. TextLoader is Dotquilt's loading placeholder for a number or a short label, such as a KPI. While it loads, its characters cross-fade through look-alikes in the shape of the answer. When the value arrives, the marks slide into the shapes of its real characters, then the value wipes in from left to right as they leave. ## Usage TextLoader is its own loading region: set its state, and put the value in as its text. The mask is the shape of the answer, such as `$00,000`; without one, the placeholder takes the shape of the current text. **React** ```tsx title="RevenueTotal.tsx" 'use client'; import { TextLoader } from '@dotquilt/react'; import { useEffect, useState } from 'react'; async function fetchTotal(month: string, signal: AbortSignal): Promise { const response = await fetch(`/api/revenue/${month}/total`, { signal }); if (!response.ok) throw new Error(`Request failed: ${response.status}`); const { total } = await response.json(); return total; } const money = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD', maximumFractionDigits: 0, }); type Result = | { status: 'loading' } | { status: 'done'; total: number } | { status: 'failed' }; export function RevenueTotal({ month }: { month: string }) { const [result, setResult] = useState({ status: 'loading' }); useEffect(() => { const request = new AbortController(); setResult({ status: 'loading' }); fetchTotal(month, request.signal) .then((total) => setResult({ status: 'done', total })) .catch(() => { if (!request.signal.aborted) setResult({ status: 'failed' }); }); return () => request.abort(); }, [month]); return (

    {result.status === 'done' ? money.format(result.total) : result.status === 'failed' ? 'Unavailable' : ''}

    ); } // Loads again whenever `month` changes. export function Dashboard() { return ; } ``` **Native** ```html title="index.html"

    ``` ```ts title="total.ts" import { registerTextLoader, type TextLoader } from 'dotquilt/text'; registerTextLoader(); const total = document.getElementById('total') as TextLoader | null; const money = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD', maximumFractionDigits: 0, }); export async function showTotal(month: string): Promise { if (!total) return; total.update({ state: 'pending', cycle: month }); try { const response = await fetch(`/api/revenue/${month}/total`); if (!response.ok) throw new Error(`Request failed: ${response.status}`); const body: { total: number } = await response.json(); // A newer request took over while this one was in flight. if (total.cycle !== month) return; // The loader's own text is the value; the characters lock into it. total.textContent = money.format(body.total); total.update({ state: 'ready' }); } catch { if (total.cycle !== month) return; total.textContent = 'Unavailable'; total.update({ state: 'ready', timing: { duration: 0 } }); } } void showTotal('2026-11'); ``` ## Options | Attribute | React | Type | Default | Description | | --- | --- | --- | --- | --- | | `state` | `state` | `pending` \| `refreshing` \| `ready` | `ready` | Whether the value 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. | | `mask` | `mask` | string | the text | The shape the placeholder shows. | | `mark` | `mark` | `dot` \| `square` \| `dash` | `dot` | Squares make a clean pixel font. Dashes read as hatching here. | | `speed` | `speed` | number | `1` | How fast the characters change. | | `pointer-response` | `pointerResponse` | `none` \| `lift` | `none` | `lift` lights the marks around the pointer while the placeholder shows, on devices with a fine pointer. | | `motion` | `motion` | `system` \| `paused` | `system` | `system` follows the visitor's reduced-motion setting; `paused` stills the characters. | | | `timing` | `{ duration?, easing? }` | | The handoff's length and curve. `{ duration: 0 }` swaps at once. | ## Animations Import alternatives from `dotquilt/animations/text` and pass them as `animations`. | Phase | Default | Also available | | --- | --- | --- | | Idle | `scramble`: characters cross-fade about every 280 ms | `scrambleCharacters`: each character changes on its own clock; `scrambleWords`: one word changes at a time, in reading order; `labelPulse`: a calm highlight moves across the placeholder | | Handoff | `morphWipe`: the marks take the real characters' shapes, then the value wipes in | `lock`: characters lock left to right, each easing in over 300 ms; `printText`: the value prints in from the left as the characters lock; `fade`: the value fades in | | Animation | Options (default) | | --- | --- | | `scramble`, `scrambleCharacters`, `scrambleWords` | `changesPerSecond` 0.5–4 | | `labelPulse` | `travelPxPerSecond` 20–140 (70) | | `morphWipe` | `travel` 0.2–0.5 (0.34), `wipeStart` 0.3–0.6 (0.46), `edge` 4–80 px (36) | | `lock`, `printText` | `staggerMs` 0–60 (40), `reelMs` 0–100 (55), `settleMs` 40–400 (300), `pop` 0–0.3 (0) | | `fade` | `duration` ms (150) | ## Languages and long text The character effect draws Latin letters, digits and punctuation (printable ASCII) on a single line, up to 256 characters. Anything else still gets a placeholder: accented or non-Latin letters, right-to-left text, text that wraps, or longer text all show a plain field of marks in the text's place, and the value fades in when it arrives. Wider character support may come in a later release. ## Accessibility While pending, the scrambled characters are hidden from assistive technology, so give the loader a label that says what is loading. When the value is ready, it is ordinary text. Source: https://dotquilt.dev/docs/components/text-loader/ --- # TypingDots > A typing indicator for chat and AI assistant replies: calm dots that hand over to the message when it arrives, as a Web Component or in React. TypingDots, Dotquilt's typing indicator, show that a reply is on its way. A slow wave passes through the dots; when the message arrives, it takes their place. ## Usage Use TypingDots as a region's placeholder, inside the same bubble your message will fill. **React** ```tsx title="AssistantReply.tsx" 'use client'; import { LoadingRegion, TypingDots } from '@dotquilt/react'; import { useEffect, useState } from 'react'; async function fetchReply( question: string, signal: AbortSignal, ): Promise { const response = await fetch('/api/assistant', { method: 'POST', body: JSON.stringify({ question }), signal, }); if (!response.ok) throw new Error(`Request failed: ${response.status}`); const { reply } = await response.json(); return reply; } export function AssistantReply({ question }: { question: string }) { const [reply, setReply] = useState(null); const [failed, setFailed] = useState(false); useEffect(() => { const request = new AbortController(); setReply(null); setFailed(false); fetchReply(question, request.signal) .then(setReply) .catch(() => { if (!request.signal.aborted) setFailed(true); }); return () => request.abort(); }, [question]); return ( } >
    {failed ? "Sorry, I couldn't answer that. Try again." : reply}
    ); } export function Chat() { return ; } ``` **Native** ```html title="index.html"
    ``` ```ts title="reply.ts" import { type LoadingRegion, registerLoadingRegion } from 'dotquilt/region'; import { registerTypingDots } from 'dotquilt/typing'; registerLoadingRegion(); registerTypingDots(); const region = document.getElementById('reply') as LoadingRegion | null; const bubble = region?.querySelector('[data-reply]'); export async function ask(question: string): Promise { if (!region || !bubble) return; region.update({ state: 'pending', cycle: question }); try { const response = await fetch('/api/assistant', { method: 'POST', body: JSON.stringify({ question }), }); if (!response.ok) throw new Error(`Request failed: ${response.status}`); const { reply }: { reply: string } = await response.json(); if (region.cycle !== question) return; bubble.textContent = reply; region.update({ state: 'ready' }); } catch { if (region.cycle !== question) return; bubble.textContent = "Sorry, I couldn't answer that. Try again."; region.update({ state: 'ready', timing: { duration: 0 } }); } } void ask('When is the Globex invoice due?'); ``` TypingDots are decorative: they have no state of their own. On their own, outside a region, they keep their wave for four seconds and then rest. ## Accessibility - **The dots are decoration.** They are hidden from assistive technology, so screen readers don't read them. - **Label the region,** for example `aria-label="Assistant reply"`, so people know what is on its way. While it is pending, the message inside is skipped. - **Announce the reply in your own words** if people need to hear it arrive, for example with a `role="log"` or `role="status"` element for the conversation. See [What screen readers hear](/docs/guides/motion/#what-screen-readers-hear). ## Options | Attribute | React | Type | Default | Description | | --- | --- | --- | --- | --- | | `count` | `count` | number | `3` | How many dots, up to 8. | | `mark` | `mark` | `dot` \| `square` \| `dash` | `dot` | The shape of each dot. | | `speed` | `speed` | number | `1` | How fast the wave moves. | | `motion` | `motion` | `system` \| `paused` | `system` | `system` follows the visitor's reduced-motion setting; `paused` stills the dots. | The dots are 8 px, 6 px apart. Change them with `--dotquilt-dot-size` and `--dotquilt-dot-gap`. Source: https://dotquilt.dev/docs/components/typing-dots/ --- # Content Security Policy > Run Dotquilt under a strict style-src, with a nonce, hashes or external stylesheets. Dotquilt draws everything with CSS and never uses inline `style` attributes, so it works under a strict Content Security Policy. Choose how its stylesheets are allowed with `stylePolicy`, and pass the same policy to every loader and region on the page. ## Nonce Generate a fresh nonce for every request, send it in your `Content-Security-Policy` header, and pass it to each component: ```tsx } > ``` ``` Content-Security-Policy: style-src 'self' 'nonce-…' ``` Never reuse a nonce across requests, and don't cache HTML that contains one. ## Hashes If you can't send a nonce, allow Dotquilt's exact stylesheets by hash. Compute them from the installed version, and recompute them whenever you upgrade: ```ts title="style-hashes.ts" import { createHash } from 'node:crypto'; import * as core from 'dotquilt/server'; /** * Every stylesheet Dotquilt may add, as CSP hashes. Recompute them whenever * you upgrade: the hashes match the exact text of one version. */ export const styleHashes = Object.values(core) .filter( (value): value is readonly string[] => Array.isArray(value) && value.every((item) => typeof item === 'string'), ) .flat() .map( (css) => `'sha256-${createHash('sha256').update(css).digest('base64')}'`, ); export const contentSecurityPolicy = `default-src 'self'; style-src 'self' ${styleHashes.join(' ')}`; ``` ## External stylesheets Serve Dotquilt's stylesheets as files, and point each component at the one for its family: ```tsx } > ``` The files ship in the package as `dotquilt/styles/.css`. Copy them into your public folder from the same installed version as your JavaScript. | File | For | | --- | --- | | `region.css` | LoadingRegion | | `skeleton.css`, `line.css`, `circle.css`, `skeleton-text.css` | each skeleton | | `skeleton-family.css` | all four skeletons in one file | | `text.css` | TextLoader | | `chart.css` | ChartLoader | | `table.css` | TableLoader | | `typing.css` | TypingDots | Set the policy before a component connects. Changing it afterwards reports an error rather than restyling the component. Source: https://dotquilt.dev/docs/guides/csp/ --- # Custom animations > Write your own idle or handoff, and bundle options into presets. Every loader has two animations: an **idle** that plays while it waits, and a **handoff** that plays when the content arrives. You can swap either for a built-in alternative, or write your own with `defineAnimation`. ```ts import { labelPulse } from 'dotquilt/animations/text'; totalLoader.animations = { idle: labelPulse() }; ``` ## Write your own An animation draws with commands, not with the DOM: an idle places marks with `dot()`, and a handoff can also move your content with `reveal()`. Dotquilt owns the timing, the restrictions and the cleanup, so a custom animation still pauses, respects reduced motion and stops after four seconds. Each `dot()` takes a centre (`x`, `y`), a radius (`size`), an `opacity` and a `tone` (`base`, or `accent` for the glow colour). The loader's `mark` decides the shape. An optional `angle`, in radians clockwise, turns squares and dashes about their centre; dots ignore it. ```ts title="animations.ts" import { defineAnimation, definePreset } from 'dotquilt/animations'; import type { SkeletonBlock } from 'dotquilt/skeleton'; /** * An idle for skeletons: a slow tide of brighter marks rolling across each * shape. `frame` draws one moment; `still` draws the resting picture used for * reduced motion, a pause and server rendering. */ export const tide = defineAnimation({ contractVersion: 1, id: 'example/tide', family: 'skeleton', phase: 'idle', options: { // Options are parsed once and frozen; reject or default anything odd here. parse: (value: Readonly>) => ({ wavelength: Math.max(40, value.wavelength ?? 120), }), }, frame({ surface, frame, dot }, { wavelength }) { for (const shape of surface.input.shapes) for (let x = shape.x + 4.5; x < shape.x + shape.width; x += 9) for (let y = shape.y + 4.5; y < shape.y + shape.height; y += 9) { const wave = Math.sin((x - frame.timeMs / 12) / (wavelength / 6.28)); dot({ x, y, size: 2.2, opacity: 0.37 + 0.2 * wave, tone: 'base' }); } }, still({ surface, dot }) { for (const shape of surface.input.shapes) for (let x = shape.x + 4.5; x < shape.x + shape.width; x += 9) for (let y = shape.y + 4.5; y < shape.y + shape.height; y += 9) dot({ x, y, size: 2.2, opacity: 0.37, tone: 'base' }); }, }); /** * A handoff for regions: content rises 8 px while it fades in. `duration` * says how long it takes; `frame` is called with the progress, from 0 to 1. */ export const rise = defineAnimation({ contractVersion: 1, id: 'example/rise', family: 'region', phase: 'handoff', options: { parse: (value: Readonly>) => ({ distance: value.distance ?? 8, }), }, duration: () => 700, prepare: () => undefined, frame({ frame, reveal }, { distance }) { reveal({ opacity: frame.progress, translateY: (1 - frame.progress) * distance, }); }, }); /** A preset bundles options you reuse: here, a calmer skeleton. */ export const calm = definePreset({ kind: 'skeleton', speed: 0.6, animations: { idle: tide({ wavelength: 200 }) }, }); const block = document.querySelector('dotquilt-skeleton-block'); if (block) block.preset = calm; ``` | Part | Idle | Handoff | | --- | --- | --- | | `family` | `skeleton`, `text`, `chart` or `table` | `region`, `skeleton`, `text`, `chart` or `table` | | `options.parse` | turns the options you pass into frozen, valid values | the same | | `frame` | draws one moment, given `frame.timeMs` | draws one moment, given `frame.progress` from 0 to 1 | | `still` | the resting picture for reduced motion and pauses | | | `duration`, `prepare` | | how long it takes, and any setup it needs once | ## Use it ```tsx ``` ## Presets `definePreset` bundles options you reuse, such as a speed and animations, and checks them once. Give it to any loader of the same kind as `preset`. Source: https://dotquilt.dev/docs/guides/custom-animations/ --- # Motion and accessibility > What screen readers hear, keyboard focus, reduced motion, pausing and the four-second limit in Dotquilt's loaders. Dotquilt's motion is slow and short by design, and every part of it can be stilled. ## Reduced motion When a visitor asks their system for reduced motion, loaders show their still picture with no glow or breathing, and the handoff swaps at once. You don't need to do anything. ## Pausing Set `motion="paused"` on any element, and every loader inside it is still. To give visitors a pause control for the whole page, set it on ``: ```ts pauseButton.addEventListener('click', () => { const paused = document.documentElement.getAttribute('motion') === 'paused'; document.documentElement.setAttribute('motion', paused ? 'system' : 'paused'); }); ``` ## The four-second limit Automatic motion never runs longer than four seconds. A loader's idle stops four seconds into a load and rests, so a long load never animates indefinitely. The handoff still plays when the content arrives, however long the load took: it lasts about a second. A handoff you ask for that is longer than four seconds is skipped. ## Focus - **Pending content is out of reach:** while a region is pending, its content is inert and hidden from assistive technology. - **Focus is kept:** if focus is inside content that becomes pending, it moves to the region. When the content is ready, focus is not moved back; your page decides. - **A focused handoff swaps at once,** so nothing moves under the keyboard. ## What screen readers hear - **The marks are silent.** Every loader is hidden from assistive technology with `aria-hidden`, and so is the placeholder layer. - **Pending content is skipped.** While a region is `pending`, its content is `inert`, hidden with `aria-hidden`, and marked `aria-busy="true"`, so screen readers don't read half-loaded content. - **Refreshing content stays readable.** While a region is `refreshing`, its content stays visible and usable, and is marked `aria-busy="true"` until it's ready. - **Ready content reads as usual.** When the region is `ready`, `aria-busy` becomes `false`. Nothing is announced on its own: see below. ## Announcements Loaders are decoration: they don't announce anything. Label every region, so people know what is loading, and announce loading and errors in your own words, for example with a `role="status"` element outside the region. ## Forced colours In Windows high-contrast mode the marks are replaced by a dotted outline in the system text colour. Source: https://dotquilt.dev/docs/guides/motion/ --- # React and Next.js > Typed React skeleton loader components with server rendering, for React 19 and the Next.js App Router. To show a skeleton loader in React, wrap the part of the page that loads in Dotquilt's ``, give it a `placeholder` such as ``, and set its `state` from your data: `pending`, `refreshing` or `ready`. The React adapter wraps the same native components in typed React components. They register themselves, render their placeholder on the server, and take their state from your props. ```tsx import { LoadingRegion, SkeletonText } from '@dotquilt/react'; ``` Each component also has its own entry point, such as `@dotquilt/react/region`, if you prefer to import only what a page uses. ## State comes from your data A region needs only two things from you: whether the data is `pending`, `refreshing` or `ready`, and a `cycle` naming the current request. Keep the request in your own state, as in the component pages' examples: - **Start a new cycle per request**, such as the id you are loading. A stale answer for an older cycle can't settle a newer one. - **Use `refreshing`** when you already show data and are fetching a newer copy: the content stays visible and usable. - **On an error**, show your message with `state="ready"` and `timing={{ duration: 0 }}`, so it replaces the placeholder at once. ## Next.js App Router The components are client components (`'use client'`), and they render on the server too: the placeholder is in the first HTML, before any JavaScript runs. Put your data loading in a client component of your own, and use it from a Server Component page: ```tsx title="app/revenue/page.tsx" // app/revenue/page.tsx: a Server Component. It renders the client component // below on the server, so the placeholder is in the first HTML. import { RevenueChart } from '@/components/revenue-chart'; export default function RevenuePage() { return (

    Revenue

    ); } ``` ```tsx title="components/revenue-chart.tsx" 'use client'; import { ChartLoader, LoadingRegion } from '@dotquilt/react'; import type { TargetProvider } from 'dotquilt/chart'; import { useEffect, useState } from 'react'; import { linePath, linePoints } from './data'; async function fetchRevenue( year: number, signal: AbortSignal, ): Promise { const response = await fetch(`/api/revenue/${year}`, { signal }); if (!response.ok) throw new Error(`Request failed: ${response.status}`); return response.json(); } type Result = | { status: 'loading' } | { status: 'done'; series: number[] } | { status: 'failed' }; export function RevenueChart({ year }: { year: number }) { const [result, setResult] = useState({ status: 'loading' }); useEffect(() => { const request = new AbortController(); setResult({ status: 'loading' }); fetchRevenue(year, request.signal) .then((series) => setResult({ status: 'done', series })) .catch(() => { if (!request.signal.aborted) setResult({ status: 'failed' }); }); return () => request.abort(); }, [year]); // Where the real line will be, in the loader's own size: the marks glide // onto it before the chart draws in. const target: TargetProvider = ({ width, height }) => result.status === 'done' ? { kind: 'line', points: linePoints(result.series, width, height), baseline: height, } : null; return ( } > {result.status === 'done' && ( )} {result.status === 'failed' && (

    We couldn't load revenue. Try again later.

    )}
    ); } export function Report() { return ; } ``` Keep functions such as `targetProvider` and custom animations inside client components: they can't be passed from a Server Component. ### Suspense Suspense and a loading region do different jobs. Suspense waits for server-side work before sending HTML; a region shows a placeholder while the browser loads data. If you stream a server component through Suspense, you can use a Dotquilt placeholder as its fallback without a region: ```tsx }> ``` A placeholder on its own is decoration, hidden from assistive technology. If the wait matters, say so in your own words nearby. ## View transitions Dotquilt works inside React's `` (and `document.startViewTransition`). A view transition shows frozen snapshots of the page while it runs, so when one is running as a region becomes ready, the region holds the first frame of its handoff and plays it in full once the transition ends. Nothing jumps when the snapshots lift. ```tsx }> {data && } ``` To let the view transition alone reveal the content, pass `timing={{ duration: 0 }}` to the region. ## Styles and CSP By default each component adds its styles inline, once per page. If your site has a Content Security Policy, pass a `stylePolicy` to every component: a nonce, or an external stylesheet. See [Content Security Policy](/docs/guides/csp/). Source: https://dotquilt.dev/docs/guides/react/ --- # Server rendering > Render placeholders on the server, so the page has its shape before JavaScript runs. A placeholder rendered on the server reserves its space in the first HTML, so the page doesn't jump when JavaScript arrives. When the components register in the browser, they take over the same elements. ## React The React components render their placeholder markup and styles on the server automatically. Render the same state on the server and in the first client render, so hydration matches. See [React and Next.js](/docs/guides/react/). ## Native `renderStatic` from `dotquilt/server` returns a loader's HTML as a string. It runs anywhere: Node, Bun, Deno or an edge function. It draws only Dotquilt's own decoration; your content comes from your own template. ```ts title="server.ts" import { renderStatic } from 'dotquilt/server'; const escapeHtml = (text: string) => text.replace( /[&<>"']/g, (c) => ({ '&': '&', '<': '<', '>': '>', '"': '"' })[c] ?? ''', ); /** * Server-renders the revenue card: the region and its placeholder come from * Dotquilt, your content from your own template. Works in Node, Bun or Deno. */ export function revenueCard(revenue: string | null, nonce?: string): string { // The same policy as your Content-Security-Policy header, for the region // and its placeholder alike. const stylePolicy = { mode: 'inline' as const, ...(nonce ? { nonce } : {}) }; const region = renderStatic({ kind: 'region', state: revenue === null ? 'pending' : 'ready', label: 'Revenue this month', placeholder: { kind: 'skeleton-text', lines: 2, stylePolicy }, stylePolicy, }); const content = `

    Revenue

    ${escapeHtml( revenue ?? '', )}

    `; // Your content goes inside the region, after the placeholder. return region.replace('', `${content}`); } ``` Then register the components in the browser, as usual. The region continues from the state the server rendered. | `kind` | Fields | | --- | --- | | `region` | `state`, `label`, `placeholder` (any loader below) | | `skeleton-block`, `skeleton-line`, `skeleton-circle` | | | `skeleton-text` | `lines`, `widths` | | `text-loader` | `text`, `mask`, `state` | | `chart-loader` | `variant` | | `table-loader` | `rows`, `rowHeight`, `columns` | | `typing-dots` | `count` | Every kind also takes `mark`, `preset` and `stylePolicy`. ## Without JavaScript If scripts never load, a pending region keeps showing its still placeholder, and your content stays visible and usable below it. Keep a way forward that works without JavaScript, such as a link to reload the page, outside the region. This is the default on purpose: a page whose bundle fails to load still works. The cost is a short moment, while JavaScript loads, when the placeholder and your server content show together and a screen reader can read content that isn't final. If you would rather hide pending content until the runtime takes over, render it with `hidden` and `inert` yourself, and remove both when it is ready. Only do this when the content has a way to appear without JavaScript, or when it is safe for it to stay hidden if scripts fail. Source: https://dotquilt.dev/docs/guides/server-rendering/ --- # Skeleton loader or spinner? > When a skeleton loader helps, when a spinner, a progress bar or nothing at all is better, and how to keep fast loads from flashing. A skeleton loader, a spinner and a progress bar all say that something is loading. They differ in what else they tell people: a skeleton shows what is coming and where, a spinner only that the page is working, and a progress bar how long is left. Choose by what is loading and how long it takes. ## Use a skeleton when you know the shape A skeleton loader suits content whose layout you know before the data arrives: a list, a feed, a card, a profile, a table, a chart, a number on a dashboard. It holds the content's place, so nothing jumps when the content arrives, and people can see where to look before it does. In Dotquilt, that's a [loading region](/docs/components/loading-region/) with a placeholder in the content's shape: - a list, card, profile or paragraph: [Skeleton](/docs/components/skeleton/); - a number or a short label, such as a KPI: [TextLoader](/docs/components/text-loader/); - a line, bar or scatter chart: [ChartLoader](/docs/components/chart-loader/); - a table whose rows load or page: [TableLoader](/docs/components/table-loader/); - a chat reply being written: [TypingDots](/docs/components/typing-dots/). ## Use a spinner for actions A spinner suits a short wait after something people did, when there's no content shape to show: a button that saves, a form that submits, a dialog that confirms. Keep it on the control that started the work. Dotquilt isn't for actions: keep your spinners there. ## Use a progress bar for long waits For a wait you can measure, such as an upload, an export or a long import, a progress bar tells people how long is left. Nielsen Norman Group's guidance is to use skeleton screens and spinners for waits under about 10 seconds, and to show progress beyond that ([Skeleton Screens 101](https://www.nngroup.com/articles/skeleton-screens/), [Progress Indicators](https://www.nngroup.com/articles/progress-indicators/)). ## Show nothing for very short waits Below about a tenth of a second, a response feels instant, and up to about a second it doesn't interrupt the flow of thought ([Response Time Limits](https://www.nngroup.com/articles/response-times-3-important-limits/)). A placeholder that appears and vanishes inside that time only flashes. A Dotquilt region has two settings for this: - `delay`: a load shorter than this never shows the placeholder, so a fast answer shows none; - `min-display`: a placeholder that did show stays at least this long, so it never flickers. Values around 150 ms and 500 ms suit most screens. See [LoadingRegion](/docs/components/loading-region/). ## Keep content visible while it refreshes When you already show data and fetch a newer copy, don't replace it with a skeleton: people lose their place. Use the region's `refreshing` state instead, which keeps the content visible and usable while the new data loads. See [LoadingRegion](/docs/components/loading-region/). ## Make it accessible Whatever you choose, label what is loading and announce the result in your own words. Dotquilt's loaders are silent and their pending content is skipped by screen readers: see [What screen readers hear](/docs/guides/motion/#what-screen-readers-hear). Source: https://dotquilt.dev/docs/guides/skeleton-or-spinner/