# Loading cats
> Four game-like loading loops with a black cat in each, all in plain CSS animation.
Four grey tiles that wait with you. A cat bounces on a trampoline, the O of LOAD stretches into a progress bar and then drops out of the word, a pile of cats falls through a trapdoor and tumbles back in, and a bar fills in four steps while cats peek in from the corners. Every loop is plain CSS keyframes.
A React component by Bruno Delorence: https://brunodelorence.com/components/loading-cats. MIT License, Copyright (c) 2026 Bruno Delorence.
Category: Feedback.
## Anatomy
1. **Stage**: The panel the tiles sit on, near-white or near-black at night. A click anywhere on it pauses or plays every loop; it is a group named by `label`.
2. **Tile**: A grey card on a 400 × 298 grid: everything inside it is placed, sized and timed in 400ths of its width, so it scales as one.
3. **Cat**: One drawing for every cat: a mochi body, pointed ears, a hooked tail, and open, sleeping or star eyes. It squashes and stretches to its box.
4. **Trampoline pad**: Gives under the landing cat: it widens, sags into a bowl and turns see-through over it, then throws it out of the top.
5. **Pill**: The O of LOAD. It stretches into a bar while a shine sweeps it three times, then drops out of the word and falls back in.
6. **Trapdoor**: Two leaves under the pile that swing down to let the cats through, then shut so they can drop back in one by one.
7. **Caption**: One of four words for the bar’s step: under half, from half, from three quarters, done. Set them with `labels`.
8. **Progress bar**: Fills in four steps on its own, or follows `progress` (0 to 1). The fill is a whole pill slid in, so a sliver is a crescent.
## When to use
- A playful wait of a few seconds that fills a screen or a panel: a game level, a first sync, an export.
- Empty or splash moments where a little character makes the wait feel shorter, and the brand can afford a joke.
- A wait with four rough milestones: drive the progress tile with `progress` and its caption and corner cat follow.
- Any size: every tile is drawn on its own 400 × 298 grid, so it looks the same from a thumbnail to a hero.
## When not to use
- Small inline waits, in a button, a field or a table row. Use a plain spinner at text size.
- Exact progress people plan around, like an upload with minutes left. Show a bar with a number and the time.
- Serious or stressful moments (a payment, an error, a medical result): cats bouncing read as not taking it seriously.
- Waits under a second: no loop gets past its first beat, and the tiles flash. Show nothing, or a skeleton.
- Errors and partial results: the tiles only know “still loading”. Say what failed in words.
## Installation
Install it with the shadcn CLI, into components/loading-cats of any React project:
```sh
npx shadcn@latest add https://brunodelorence.com/r/loading-cats.json
```
Or copy all the source files below into one folder of your project. Either way it needs React 19 and a bundler with CSS Modules (Next.js, Vite).
It has a dark colour scheme. Its colours are CSS light-dark() pairs, kept inside @supports so that builds which rewrite light-dark() for older browsers leave them alone: it follows your page’s color-scheme (light unless the page sets one) or its colorScheme prop, with nothing to configure. Browsers without light-dark() show it light.
## Usage
```tsx
import { LoadingCats } from './loading-cats';
export function Uploading({ sent, total }: { sent: number; total: number }) {
return (
);
}
```
## States
- **Still**: With `autoplay={false}`, when paused, or under reduced motion: the cat on its pad, the stretched pill, the full pile and the bar half way.
- **Progress, under half**: `progress={0.25}`: the first caption, and a cat peeks in from the bottom-right corner.
- **Progress, half way**: From 0.5 the second caption, and the cat swings in from the top-left instead.
- **Progress, almost**: From 0.75 the third caption; the cat moves to the bottom-left.
- **Progress, done**: At 1 the last caption, and a cat leans in from all four corners at once.
- **Dark**: Every colour is a light-dark() token: at night light cats on charcoal tiles. `colorScheme` forces one.
- **One tile**: `animations` picks which tiles and in what order; a single tile is centred, at most 480 px wide.
## How it works
- Every tile is drawn on a 400 × 298 grid. A tile is a size container and --u is a 400th of its width, so positions, strokes, type and even the keyframes’ distances scale with the tile; one stylesheet draws it at 140 px or at 440 px.
- Each loop is a set of keyframes written frame by frame at 30 fps, as dense linear steps with eased spans in between: the bounce runs 1.8 s, the word 5.5 s, the pile 3 s and the progress bar 8.8 s, each with a negative delay that starts it mid-loop.
- The cats move with the individual translate, rotate and scale properties, each from its own animation, so a fall (ease-in), a tilt and a squash (scaled about the bottom of the body) keep their own timing on one element.
- The trampoline is a see-through pad drawn over the cat: it widens and sags into a bowl (border-radius with an elliptical bottom) as the cat sinks in, pinches to 199 units, then springs back past its width and settles. The dust is four discs that fly out from under the cat and shrink away.
- LOAD is three drawn capitals and a ring of the same 15.5-unit weight in a centred flex row. Only the O’s slot changes width: wide, it spreads the word into a pill (with an expo ease and an overshoot); at zero, the word closes to LAD while the ring falls out with an ease-in and later drops back in with an ease-out. A 30° slanted band, clipped by the pill’s inside, sweeps it three times.
- The trapdoor’s two leaves turn about hinges just past the tile’s sides, to 60° and back with a small overshoot and a dip as each cat lands. The cats fall through with gravity, wait off the tile, then drop back in one by one, stretched as they fall and squashed as they land.
- Each corner of the progress tile is the bottom-right one mirrored about the tile’s middle (rotate(180deg), scaleX(-1), scaleY(-1)), so one swing, round a point past the tile’s right side, serves all four. The fill is a whole pill slid in from the left, so a sliver of it reads as a crescent.
- With progress set, the progress tile leaves its loop: the fill, the caption and the corner cat follow the value with transitions. Without it, under reduced motion or with the loops paused, every tile falls back to its base styles, which are the stills.
- The cat is one SVG on a 150 × 104 grid (ears and tail first, so the body covers their roots), stretched to each box with preserveAspectRatio none; the pile’s loafing cats are just flatter boxes. Its colour is currentColor, its eyes and inner ears a token, so the grey cats and the night scheme cost nothing.
- Every colour is a light-dark() token on the root: by day near-black cats on light-grey tiles, at night light cats with dark eyes on charcoal tiles.
## API reference
- **animations** (`('bounce' | 'word' | 'pile' | 'progress')[]`, default `all four`): Which tiles to show, in this order. One tile is drawn alone, up to 480 px wide.
- **labels** (`[string, string, string, string]`, default `['Loading', 'Halfway', 'Almost', 'Done!']`): The progress tile’s captions: under half, from half, from three quarters, and done.
- **progress** (`number`): Drives the progress tile, from 0 to 1, instead of its loop; its caption and corner cat follow the value.
- **label** (`string`, default `'Loading'`): What the group of tiles is called for screen readers.
- **onPausedChange** (`(paused: boolean) => void`): Called when the reader pauses (true) or plays (false) the loops, by a click or the button.
- **autoplay** (`boolean`, default `true`): Play the loops while the tiles are on screen. Without it every tile shows its still: the cat on its pad, the stretched pill, the full pile and the bar half way.
- **colorScheme** (`'light' | 'dark' | 'system'`): Its colours: light, dark, or the reader’s system setting. Without it the component follows the page’s color-scheme, which is light unless the page sets one.
- **className** (`string`): Extra class for the root.
## Accessibility
- The tiles are a group named by label. The bounce, word and pile tiles are images with a short description; the drawings inside them are aria-hidden.
- The progress tile is a progressbar named by the first caption. With progress set it reports its value (0–100) and a value text with the current caption; without it, it is an indeterminate progressbar.
- A Pause animations toggle button (aria-pressed) sits in the stage’s corner: it shows on hover and on keyboard focus, with a focus ring. Clicking or tapping any tile toggles the loops too, so the motion can always be stopped.
- The loops pause off screen and in a hidden tab. Under reduced motion they never play and the toggle is hidden: every tile shows its still, and a value-driven bar jumps without transitions.
## Source
### loading-cats/loading-cats.tsx
```tsx
// Copyright (c) 2026 Bruno Delorence. MIT License.
'use client';
import { useState, type CSSProperties } from 'react';
import { Cat, Letter, type Eyes } from './cat';
import { useAutoplay } from './use-autoplay';
import styles from './loading-cats.module.css';
/*
* Loading cats: four game-like loading loops in grey tiles, every one of them plain CSS
* animation.
*
* - Bounce: a cat drops onto a pad that gives like a trampoline (it widens, sags and turns
* see-through over the cat), springs off it in a puff of dust and sails out of the top.
* - Word: the O of LOAD stretches into a pill and a shine sweeps it three times; it shrinks back,
* drops out of the word (L AD, LAD) and falls back in from above.
* - Pile: a heap of cats sits on a two-leaf trapdoor; the leaves swing down, the cats fall through,
* the leaves swing shut, and the cats drop back in one by one, squashing as they land.
* - Progress: a bar fills in four steps, each with its caption; at each step a cat swings in from
* another corner, and at the last one, from all four.
*
* Every tile is drawn on a 400 × 298 grid: --u is one unit, a 400th of the tile's width (a
* container query), so a tile looks the same at any size. The loops are keyframes timed frame
* by frame at 30 fps; the cats move by the individual translate, rotate and scale properties, so a
* fall, a tilt and a squash can each keep their own timing.
*
* While part of it is on screen the loops play; off screen or in a hidden tab they pause where they
* are. With autoplay off, when the reader pauses them, or under reduced motion, every tile shows a
* still: the cat on its pad, the stretched pill, the full pile, and the bar half way.
*/
export type LoadingCatsAnimation = 'bounce' | 'word' | 'pile' | 'progress';
const ALL: LoadingCatsAnimation[] = ['bounce', 'word', 'pile', 'progress'];
const LABELS: [string, string, string, string] = ['Loading', 'Halfway', 'Almost', 'Done!'];
/** n units of the tile's grid, as CSS. */
const u = (n: number) => `calc(var(--u) * ${n})`;
/** A box on the tile's grid, and the point (in the box's own units) it turns and squashes about. */
function box(
left: number,
top: number,
width: number,
height: number,
origin?: [number, number],
): CSSProperties {
return {
left: u(left),
top: u(top),
width: u(width),
height: u(height),
transformOrigin: origin ? `${u(origin[0])} ${u(origin[1])}` : undefined,
};
}
/** The step of the bar a progress belongs to: its caption and its corner cat. */
const stageOf = (progress: number) =>
progress >= 1 ? 3 : progress >= 0.75 ? 2 : progress >= 0.5 ? 1 : 0;
function BounceTile() {
return (
{/* The body's bottom middle, (64, 102), rests on the pad's top at y 243. */}
);
}
function WordTile() {
return (
);
}
/*
* The pile, back to front: the sleeping cat on top, the left cat, the front cat, and the cat on
* its side against the right wall. Each box is the 150 × 104 drawing stretched to that cat's
* proportions; the origin is the bottom middle of its body, where it squashes on landing.
*/
const PILE: { eyes: Eyes; tone: 'ink' | 'soft'; name: string; style: CSSProperties }[] = [
{
eyes: 'sleep',
tone: 'ink',
name: 'pileD',
style: box(73.3, 23.4, 177.5, 107.7, [75.7, 105.7]),
},
{ eyes: 'star', tone: 'soft', name: 'pileA', style: box(3.4, 108.8, 171, 105, [73.1, 103]) },
{ eyes: 'open', tone: 'ink', name: 'pileB', style: box(143, 94, 181.5, 119.6, [77.4, 117.3]) },
{
eyes: 'star',
tone: 'soft',
name: 'pileC',
style: { ...box(269.3, 74.7, 177.5, 111.3, [75.7, 64.3]), transform: 'rotate(-84deg)' },
},
];
function PileTile() {
return (
{PILE.map(({ eyes, tone, name, style }) => (
))}
);
}
const CORNERS = ['br', 'tl', 'bl', 'tr'] as const;
function ProgressTile({ labels, progress }: { labels: readonly string[]; progress?: number }) {
const controlled = progress != null;
// Uncontrolled, the loop plays; its still (no motion, or paused) is the bar half way.
const value = controlled ? Math.min(1, Math.max(0, progress)) : 0.5;
const stage = stageOf(value);
return (
{CORNERS.map((corner) => (
{/* A round head tilted 12° towards its corner, the eyes' midpoint at (327, 237). */}
))}
{labels.slice(0, 4).map((text, index) => (
{text}
))}
);
}
export function LoadingCats({
animations = ALL,
labels = LABELS,
progress,
label = 'Loading',
autoplay = true,
colorScheme,
className = '',
onPausedChange,
}: {
/** Which tiles to show, in this order. */
animations?: LoadingCatsAnimation[];
/** The progress tile's four captions: under half, from half, from three quarters, and done. */
labels?: readonly [string, string, string, string];
/** Drives the progress tile (0 to 1) instead of its loop; its caption and corner cat follow. */
progress?: number;
/** What the group of tiles is called for screen readers. */
label?: string;
/** Play the loops while on screen; without it every tile shows its still. */
autoplay?: boolean;
/** Light or dark colours, or the reader's ('system'); without it, the page's color-scheme. */
colorScheme?: 'light' | 'dark' | 'system';
className?: string;
/** Called when the reader pauses (true) or plays (false) the loops, by a click or the button. */
onPausedChange?: (paused: boolean) => void;
}) {
const { ref, playing } = useAutoplay();
/** The reader's own play or pause, which outlasts the autoplay prop until it changes. */
const [chosen, setChosen] = useState<{ on: boolean; autoplay: boolean } | null>(null);
const on = chosen && chosen.autoplay === autoplay ? chosen.on : autoplay;
const toggle = () => {
setChosen({ on: !on, autoplay });
onPausedChange?.(on);
};
const run = !on ? 'still' : playing ? 'play' : 'pause';
const shown = ALL.filter((name) => animations.includes(name)).sort(
(a, b) => animations.indexOf(a) - animations.indexOf(b),
);
return (
{shown.map((name) =>
name === 'bounce' ? (
) : name === 'word' ? (
) : name === 'pile' ? (
) : (
),
)}