# Sync status
> A sync pill that turns red when a sync fails, while a round retry button buds off it like a drop of liquid and flows back in on retry.
“Syncing” settles on “Synced” with a check. A failure turns the pill red, and a round retry button, in ink, swells out of its end, stretches a gooey neck and snaps free. Retry, and the button flows back into the pill, which syncs again; switch the stage to Offline to make syncs fail.
A React component by Bruno Delorence: https://brunodelorence.com/components/sync-status. MIT License, Copyright (c) 2026 Bruno Delorence.
Category: Feedback.
## Anatomy
1. **Stage**: A rounded panel that sets the type size from its own width (a container query), so the pill grows with the room it has.
2. **Pill**: The status itself, raised on the stage with a hairline and a soft shadow. Its width follows the words, and springs to the new one when they change.
3. **Status icon**: A ten-dot spinner, a green check or a red alert. The old icon shrinks and blurs out as the new one springs in.
4. **Label**: Only its end changes (“Sync|ing”, “Sync|ed”, “Sync| failed”), rising in with a touch of blur; red on a failure.
5. **Retry button**: Shown only on a failure: it buds off the pill’s round end like a drop of liquid and flows back in when pressed. Labelled “Retry sync”.
6. **Sync now**: Starts a sync at any time; `aria-disabled` and greyed while one runs. Focus lands here when the retry button goes.
7. **Offline switch**: A real `role="switch"` that makes the simulated sync fail. It is left out when you pass your own `sync`.
## When to use
- Saying whether local changes have reached the server: a notes app, a design tool, a shared document.
- Background work with three outcomes worth telling apart at a glance: `Syncing`, `Synced`, `Sync failed`.
- A failure the person can fix themselves by trying again: the retry button appears right where they are looking.
- A status that changes on its own while the person keeps working: every change is announced politely to screen readers.
## When not to use
- Progress that can be measured, like an upload of 40 MB. Use a progress bar with a percentage.
- Errors that need more than a retry (a conflict, a full disk, a sign-in). Use a banner or a dialog that says what to do.
- One-off confirmations like “Saved”. A toast that leaves on its own is quieter.
- Dense toolbars where a 44 px pill and a moving button don’t fit. Use a small icon with a tooltip.
- Several things syncing at once. Show a status per item, or a list, not one pill for all.
## Installation
Install it with the shadcn CLI, into components/sync-status of any React project:
```sh
npx shadcn@latest add https://brunodelorence.com/r/sync-status.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 { SyncStatus } from './sync-status';
async function syncProject() {
const response = await fetch('/api/sync', { method: 'POST' });
if (!response.ok) throw new Error('Sync failed');
}
// Resolves: Synced. Rejects: Sync failed, with the retry button.
export default function ProjectSync() {
return ;
}
```
## States
- **Synced**: The resting state: a green check and “Synced”. Sync now is ready.
- **Syncing**: The spinner keeps turning, in ten steps a second; nothing else moves. Sync now is greyed.
- **Sync failed**: The words turn red, the alert shows, and the retry button sits beside the pill in the ink colour.
- **Offline on**: Still synced, but the switch is red: the next simulated sync will fail.
- **Dark**: With `colorScheme="dark"` every token takes its dark side; the retry button turns light.
## How it works
- At rest it is plain HTML and CSS: the pill and the button side by side, centred, so it renders without JavaScript.
- Between states, one SVG layer draws the pill, the button and the goo for the length of the move. Closed-form springs drive it in a requestAnimationFrame loop that stops once they settle. The pill’s place and width come from the layouts before and after the change (FLIP), and the words ride along with a transform and a clip.
- The goo is the classic metaball bridge between the pill’s round end and the button (goo.ts). It spreads while they overlap and narrows to a thread as they part; pulling away, it stretches further before snapping, and coming back, it joins sooner.
- The button buds off white from inside the pill and turns to ink as it gets away, along a gradient neck. A lively spring makes it overshoot, so the thread snaps, then settles.
- Only the end of the label changes (“Sync|ing”, “Sync|ed”, “Sync| failed”), cross-fading with a little blur. The spinner, the check and the alert swap the same way.
- Every colour is a light-dark() token on the root, so it follows the page’s color-scheme, or the colorScheme prop. While the goo moves, the script reads the pill’s and the button’s resolved colours from the SVG layer each frame, so a switch mid-move follows on the next frame.
## API reference
- **sync** (`() => Promise`): Runs a sync: resolves when it is done, rejects or throws when it fails. Without it, the stage simulates a 1.6 s sync, which fails while its Offline switch is on (the switch is hidden when sync is given).
- **defaultState** (`'syncing' | 'synced' | 'failed'`, default `'synced'`): Opens in this state, at rest; no sync runs for it, so 'syncing' spins until one starts. Setting it turns the demo off.
- **defaultOffline** (`boolean`, default `false`): Opens with the Offline switch on, so the next simulated sync fails. Setting it turns the demo off.
- **autoplay** (`boolean`, default `true`): While on screen and untouched, a demo pointer syncs, fails and retries on its own.
- **colorScheme** (`'light' | 'dark' | 'system'`): Forces light or dark colours, or follows the reader’s system setting; without it the component takes the page’s color-scheme, which is light unless the page sets one.
- **className** (`string`): Extra class for the root, a stage of its own.
## Accessibility
- States are announced in a polite live region: “Syncing.”, “Synced.”, “Sync failed. Retry?”.
- Retry, Sync now and Offline (a switch, with aria-checked) are real buttons. While a sync runs, Sync now is aria-disabled but stays focusable.
- When the retry button leaves with the failure, focus moves to Sync now instead of being lost.
- Under reduced motion there is no goo or spring, and the spinner stands still.
## Source
### sync-status/sync-status.tsx
```tsx
// Copyright (c) 2026 Bruno Delorence. MIT License.
'use client';
import { useEffect, useId, useLayoutEffect, useRef, useState, type CSSProperties } from 'react';
import { bridge } from './goo';
import { GhostPointer, runDemo } from './ghost-pointer';
import { useAutoplay } from './use-autoplay';
import styles from './sync-status.module.css';
/*
* Sync status: a pill that says how the sync is going. "Syncing", with a spinner, settles on
* "Synced" with a check; when a sync fails the pill turns red, "Sync failed", and a round black
* retry button buds off its end and pulls away, like a drop of liquid splitting in two. Retry
* and the button flows back into the pill, which syncs again.
*
* - At rest, everything is plain HTML and CSS: the pill and the button, side by side, centred.
* - Between states, the shapes are drawn in one SVG layer for the length of the move: the pill,
* the button and the goo between them (goo.ts), all driven by springs in a requestAnimationFrame
* loop that stops when they settle. The pill's width and place come from the layouts before and
* after the change (FLIP); the button leaves from inside the pill's round end, in the pill's
* colour, and takes its own as it gets away.
* - The words cross-fade with a touch of blur; only the end changes ("Sync|ing", "Sync|ed",
* "Sync| failed").
* - The demo syncs, then fails, then a ghost pointer retries; under reduced motion states change
* at once and the demo does not run.
* - Light or dark: every colour is a light-dark() token in the CSS, so the scheme is the page's
* color-scheme, or the one the colorScheme prop sets. The moving bud's colours are mixed from
* the two the CSS resolves for the SVG layer, read as it draws.
*/
export type SyncState = 'syncing' | 'synced' | 'failed';
/** How long the simulated sync takes, in ms. */
const SYNC_TIME = 1600;
/** The end of the label after "Sync", for each state. */
const ENDINGS: Record = {
syncing: 'ing',
synced: 'ed',
failed: ' failed',
};
const ANNOUNCEMENTS: Record = {
syncing: 'Syncing.',
synced: 'Synced.',
failed: 'Sync failed. Retry?',
};
/** A damped spring, from 0 to 1: `damping` below 1 overshoots, `frequency` sets the pace. */
type Spring = { damping: number; frequency: number };
/** The pill moving and resizing. */
const SHAPE: Spring = { damping: 0.78, frequency: 14 };
/** The button pulling away: lively, so the goo stretches and snaps. */
const SPLIT: Spring = { damping: 0.5, frequency: 13 };
/** The button flowing back in. */
const MERGE: Spring = { damping: 0.85, frequency: 16 };
/** The spring's value `t` seconds in. */
function spring(t: number, { damping, frequency }: Spring) {
if (t <= 0) return 0;
const decay = damping * frequency;
const swing = frequency * Math.sqrt(1 - damping * damping);
return 1 - Math.exp(-decay * t) * (Math.cos(swing * t) + (decay / swing) * Math.sin(swing * t));
}
/** How long until it is still, in seconds (within a thousandth). */
const settled = ({ damping, frequency }: Spring) => 6.9 / (damping * frequency);
const lerp = (from: number, to: number, t: number) => from + (to - from) * t;
const smoothstep = (from: number, to: number, x: number) => {
const t = Math.min(1, Math.max(0, (x - from) / (to - from)));
return t * t * (3 - 2 * t);
};
/** A computed sRGB colour's red, green and blue, from 0 to 255; null for other colour spaces. */
const channels = (colour: string) => {
const legacy = colour.startsWith('rgb');
if (!legacy && !colour.startsWith('color(srgb ')) return null;
const values = (colour.match(/[\d.]+/g) ?? []).slice(0, 3).map(Number);
return values.length === 3 ? values.map((value) => (legacy ? value : value * 255)) : null;
};
/**
* The pill's colour turning to the button's, `t` from 0 to 1. sRGB colours mix to rgb(), so the
* goo's gradient blends in sRGB, as it always has; colours in other spaces go to color-mix().
*/
const mix = (from: string, to: string, t: number) => {
const [a, b] = [channels(from), channels(to)];
if (!a || !b) return `color-mix(in srgb, ${to} ${t * 100}%, ${from})`;
return `rgb(${a.map((channel, i) => Math.round(lerp(channel, b[i], t))).join(' ')})`;
};
/** Where the shapes are, in px in the group's box: the pill, and the button's centre if out. */
type Shapes = { left: number; width: number; bud: number | null };
/** A move between two layouts. */
type Motion = { from: Shapes; to: Shapes; start: number; snapped: boolean };
const reducedMotion = () => window.matchMedia('(prefers-reduced-motion: reduce)').matches;
export function SyncStatus({
sync,
autoplay = true,
colorScheme,
defaultState,
defaultOffline,
className = '',
}: {
/**
* Runs a sync: resolves when it is done, rejects when it fails. Without it, the stage simulates
* one (1.6 s), which fails while its Offline switch is on.
*/
sync?: () => Promise;
/** While on screen and untouched, a demo pointer plays with it on its own. */
autoplay?: boolean;
/**
* Light or dark colours, or the system's ('system' follows the reader's setting). Without it,
* it takes the page's color-scheme, which is light unless the page says otherwise.
*/
colorScheme?: 'light' | 'dark' | 'system';
/**
* Opens in this state, at rest, instead of "Synced". No sync runs for it: "syncing" spins until
* a sync is started elsewhere. Setting it turns the demo off.
*/
defaultState?: SyncState;
/** Opens with the Offline switch on, so the next simulated sync fails. Turns the demo off. */
defaultOffline?: boolean;
className?: string;
}) {
const { ref: root, playing, take } = useAutoplay(6000);
const [state, setState] = useState(defaultState ?? 'synced');
// A status opened in a given state is shown as it is: no demo plays with it.
const demo = autoplay && defaultState === undefined && defaultOffline === undefined;
/** Counts the changes, to key the icons and words. */
const [version, setVersion] = useState(0);
/**
* The state before the last change, whose icon and words leave as the new ones come in. They
* stay, invisible: their exit animation starts from visible, so nothing has to clear them.
*/
const [previous, setPrevious] = useState<{ state: SyncState; version: number } | null>(null);
const [offline, setOffline] = useState(defaultOffline ?? false);
const [message, setMessage] = useState('');
const gradient = useId();
const group = useRef(null);
const pill = useRef(null);
const retry = useRef(null);
const syncNow = useRef(null);
const layer = useRef(null);
const pillShape = useRef(null);
const goo = useRef(null);
const gooEnd = useRef(null);
const gooGradient = useRef(null);
const bud = useRef(null);
const budIcon = useRef(null);
const pointer = useRef(null);
/** Where the shapes were when the state changed, to move from there. */
const before = useRef(null);
const motion = useRef(null);
/** The shapes as last drawn, so a change in mid-move starts from where they are. */
const drawn = useRef(null);
const frame = useRef(0);
/** Counts the syncs, so only the latest one's result lands. */
const runs = useRef(0);
/** The state of the latest render, for the syncs' results, which land later. */
const latest = useRef({ state, version });
const refocus = useRef(false);
const stopDemo = useRef<(() => void) | null>(null);
/** Repeats are made to differ, so screen readers announce them again. */
const announce = (text: string) => setMessage((now) => (now === text ? `${text}\u00a0` : text));
/** The shapes at rest, as laid out now. */
const measure = (): Shapes | null => {
const box = group.current?.getBoundingClientRect();
const shape = pill.current?.getBoundingClientRect();
const button = retry.current?.getBoundingClientRect();
if (!box || !shape || !group.current) return null;
// Screen pixels to the group's own, should the stage sit in a scaled container.
const scale = box.width / group.current.offsetWidth || 1;
return {
left: (shape.left - box.left) / scale,
width: shape.width / scale,
bud: button?.width ? (button.left + button.width / 2 - box.left) / scale : null,
};
};
const change = (next: SyncState) => {
const now = latest.current;
if (now.state === next) return;
before.current = reducedMotion() ? null : (drawn.current ?? measure());
// The retry button goes with the failure: the focus moves to Sync now.
refocus.current = document.activeElement === retry.current;
latest.current = { state: next, version: now.version + 1 };
setPrevious({ state: now.state, version: now.version });
setState(next);
setVersion(now.version + 1);
announce(ANNOUNCEMENTS[next]);
};
/** A simulated sync, `SYNC_TIME` long. */
const simulate = (succeed: boolean) =>
new Promise((resolve, reject) => {
window.setTimeout(() => (succeed ? resolve() : reject(new Error('Offline'))), SYNC_TIME);
});
/** Syncs: with the reader's function, or the simulation (forced to `outcome` by the demo). */
const run = (outcome?: boolean) => {
if (state === 'syncing') return;
const id = (runs.current += 1);
change('syncing');
const attempt = () => (sync ? sync() : simulate(!offline));
// A function that throws fails like one that rejects.
const job = outcome === undefined ? Promise.resolve().then(attempt) : simulate(outcome);
job.then(
() => runs.current === id && change('synced'),
() => runs.current === id && change('failed'),
);
};
/** Draws the shapes at `now`; false once they have settled. */
const draw = (now: number) => {
const move = motion.current;
const height = pill.current?.offsetHeight ?? 0;
if (!move || !height) return false;
const r = height / 2;
const t = (now - move.start) / 1000;
const p = spring(t, SHAPE);
const left = lerp(move.from.left, move.to.left, p);
const width = lerp(move.from.width, move.to.width, p);
// The centre of the pill's round right end, where the button comes out and goes back in.
const end = left + width - r;
const endOf = (shapes: Shapes) => shapes.left + shapes.width - r;
let x: number | null = null;
let duration = settled(SHAPE);
if (move.from.bud === null && move.to.bud !== null) {
// It pulls away from the end, a moment after the pill starts to change.
x = end + (move.to.bud - endOf(move.to)) * spring(t - 0.06, SPLIT);
duration = Math.max(duration, settled(SPLIT) + 0.06);
} else if (move.from.bud !== null && move.to.bud === null) {
x = end + (move.from.bud - endOf(move.from)) * (1 - spring(t, MERGE));
duration = Math.max(duration, settled(MERGE));
} else if (move.from.bud !== null && move.to.bud !== null) {
x = lerp(move.from.bud, move.to.bud, p);
}
pillShape.current?.setAttribute('x', left.toFixed(2));
pillShape.current?.setAttribute('width', width.toFixed(2));
pillShape.current?.setAttribute('height', height.toFixed(2));
pillShape.current?.setAttribute('rx', r.toFixed(2));
if (x === null) {
bud.current?.setAttribute('r', '0');
goo.current?.setAttribute('d', '');
budIcon.current?.setAttribute('opacity', '0');
} else {
const distance = x - end;
// The pill's colour inside it, the button's own once it is away. Both are read from the CSS
// each frame, so they follow the colour scheme, even should it change during the move.
const colours = layer.current && getComputedStyle(layer.current);
const ink = smoothstep(r, 2.2 * r, distance);
const shade = colours ? mix(colours.fill, colours.color, ink) : '';
bud.current?.setAttribute('cx', x.toFixed(2));
bud.current?.setAttribute('cy', r.toFixed(2));
bud.current?.setAttribute('r', r.toFixed(2));
bud.current?.style.setProperty('fill', shade);
// Pulling away, the goo stretches until it snaps for good; coming back, it joins sooner.
const splitting = move.to.bud !== null;
const reach = (splitting ? 2.62 : 2.3) * r;
if (splitting && distance >= reach) move.snapped = true;
const path = move.snapped ? '' : bridge({ x: end, y: r, r }, { x, y: r, r }, reach);
goo.current?.setAttribute('d', path);
// The pill's colour at its edge, the button's at its centre.
gooGradient.current?.setAttribute('x1', (end + r * 0.8).toFixed(2));
gooGradient.current?.setAttribute('x2', Math.max(end + r, x).toFixed(2));
gooEnd.current?.style.setProperty('stop-color', shade);
const size = height * 0.44;
budIcon.current?.setAttribute(
'transform',
`translate(${(x - size / 2).toFixed(2)} ${(r - size / 2).toFixed(2)}) scale(${(size / 20).toFixed(3)})`,
);
budIcon.current?.setAttribute('opacity', (ink * ink).toFixed(3));
}
// The words ride on the pill, clipped to its right end as it narrows or widens.
const words = pill.current;
if (words) {
words.style.transform = `translateX(${(left - move.to.left).toFixed(2)}px)`;
words.style.clipPath = `inset(-4px ${(move.to.width - width).toFixed(2)}px -4px -4px)`;
}
drawn.current = { left, width, bud: x };
return t < duration;
};
const finish = () => {
motion.current = null;
drawn.current = null;
group.current?.removeAttribute('data-goo');
pill.current?.style.removeProperty('transform');
pill.current?.style.removeProperty('clip-path');
};
// After a change: from where the shapes were to where the new layout puts them.
useLayoutEffect(() => {
if (refocus.current) {
refocus.current = false;
syncNow.current?.focus();
}
const from = before.current;
before.current = null;
const element = group.current;
if (!from || !element) return;
cancelAnimationFrame(frame.current);
finish();
const to = measure();
if (!to) return;
motion.current = { from, to, start: performance.now(), snapped: false };
element.setAttribute('data-goo', '');
draw(performance.now());
const loop = () => {
if (draw(performance.now())) frame.current = requestAnimationFrame(loop);
else finish();
};
frame.current = requestAnimationFrame(loop);
// `measure`, `draw` and `finish` read refs only; the state is all this depends on.
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [state]);
// Nothing keeps moving, and no sync lands, once the status is gone.
useEffect(
() => () => {
cancelAnimationFrame(frame.current);
runs.current += 1;
},
[],
);
// The demo calls the handlers of the latest render.
const actions = useRef({ run, state });
useLayoutEffect(() => {
actions.current = { run, state };
});
// The demo: a sync that works, one that fails, and a ghost pointer that retries; again while on
// screen and untouched. The demo decides each outcome; the Offline switch is the reader's.
useEffect(() => {
const stage = root.current;
const ghost = pointer.current;
if (!demo || !playing || !stage || !ghost) return;
const stop = runDemo(stage, ghost, async ({ wait, moveTo, press }) => {
const act = () => actions.current;
const retryNow = async () => {
await moveTo(retry.current);
await wait(350);
await press(() => act().run(true));
await wait(SYNC_TIME + 1500);
await moveTo(stage, { x: 0.7, y: 0.82 });
};
await wait(700);
for (;;) {
// A failure the reader left is retried first.
if (act().state === 'failed') await retryNow();
act().run(true);
await wait(SYNC_TIME + 1600);
act().run(false);
await wait(SYNC_TIME + 1100);
await retryNow();
}
});
stopDemo.current = stop;
return stop;
}, [demo, playing, root]);
/** The reader takes over: the demo stops at once, and waits until they leave it alone. */
const readerActs = () => {
stopDemo.current?.();
stopDemo.current = null;
take();
};
const failed = state === 'failed';
const busy = state === 'syncing';
return (