Micro-interactions

Preloader

A percentage-counting load overlay — spinning ring, eased counter, and a fade-out that reveals the page beneath.

Cook BookLoop Number ticker Fade in / Fade out Easing Perceived performance

Controls

duration3.0 s

ringColor

#a855f7

overlayColor

#000000

ringSize128 px

spinSpeed1.5 s

holdDelay0.4 s

fadeDuration0.60 s

showLabel

Install

bun add gsap clsx tailwind-merge

Then copy 2 files into your project:

components/registry/preloader/preloader.tsx
lib/utils.ts

Props

Prop	Type	Default	Description
duration	number	3	Simulated load time.
ringColor	string (hex)	"#a855f7"	Color of the spinner, counter, and label.
overlayColor	string (hex)	"#000000"	Overlay background color.
ringSize	number	128	Ring diameter.
spinSpeed	number	1.5	Seconds per spinner revolution.
holdDelay	number	0.4	Pause at 100% before the fade.
fadeDuration	number	0.6	Duration of the fade-out.
showLabel	boolean	true	Show the caption under the counter.

What It Demonstrates

Loop: An animation that repeats, a set number of times or infinitely.
Number ticker: Digits rolling or counting up to a value.
Fade in / Fade out: Element appears or disappears by changing opacity.
Easing: The rate at which an animation speeds up or slows down.
Perceived performance: The right animation makes an interface feel faster, even when it isn't.

Related Components

Appears In

React Micro-Interaction Components

"use client"; import { useEffect, useRef } from "react"; import gsap from "gsap"; import { cn } from "@/lib/utils"; export interface PreloaderProps { simulate?: boolean; duration?: number; holdDelay?: number; fadeDuration?: number; ringColor?: string; overlayColor?: string; ringSize?: number; spinSpeed?: number; label?: string; showLabel?: boolean; progress?: number; isComplete?: boolean; onComplete?: () => void; reducedMotion?: boolean; className?: string; } export default function Preloader({ simulate = false, duration = 3, holdDelay = 0.4, fadeDuration = 0.6, ringColor = "#a855f7", overlayColor = "#000000", ringSize = 128, spinSpeed = 1.5, label = "Loading Experience", showLabel = true, progress = 0, isComplete = false, onComplete, reducedMotion = false, className, }: PreloaderProps) { const rootRef = useRef<HTMLDivElement>(null); const counterRef = useRef<HTMLSpanElement>(null); const onCompleteRef = useRef(onComplete); onCompleteRef.current = onComplete; const writeCount = (v: number) => { if (counterRef.current) { counterRef.current.textContent = String(Math.round(v)); } }; useEffect(() => { if (!simulate || reducedMotion) return; const ctx = gsap.context(() => { const proxy = { v: 0 }; const tl = gsap.timeline(); tl.to(proxy, { v: 100, duration, ease: "power2.inOut", onUpdate: () => writeCount(proxy.v), }); tl.to(rootRef.current, { opacity: 0, duration: fadeDuration, ease: "power2.inOut", delay: holdDelay, onComplete: () => { if (rootRef.current) rootRef.current.style.display = "none"; onCompleteRef.current?.(); }, }); }, rootRef); return () => ctx.revert(); }, [simulate, reducedMotion, duration, holdDelay, fadeDuration]); useEffect(() => { if (simulate || reducedMotion) return; const proxy = { v: Number(counterRef.current?.textContent) || 0 }; const tween = gsap.to(proxy, { v: Math.min(100, Math.max(0, progress)), duration: 0.5, ease: "power2.out", onUpdate: () => writeCount(proxy.v), }); return () => { tween.kill(); }; }, [simulate, reducedMotion, progress]); useEffect(() => { if (simulate || reducedMotion || !isComplete) return; const tween = gsap.to(rootRef.current, { opacity: 0, duration: fadeDuration, ease: "power2.inOut", onComplete: () => { if (rootRef.current) { rootRef.current.style.pointerEvents = "none"; rootRef.current.style.display = "none"; } onCompleteRef.current?.(); }, }); return () => { tween.kill(); }; }, [simulate, reducedMotion, isComplete, fadeDuration]); const staticCount = reducedMotion ? simulate ? 100 : Math.round(progress) : 0; return ( <div ref={rootRef} className={cn( "absolute inset-0 z-40 flex items-center justify-center", className, )} style={{ background: overlayColor }} > <div className="flex flex-col items-center gap-6"> <div className="relative" style={{ width: ringSize, height: ringSize }} > <div className="absolute inset-0 rounded-full border-2 border-white/20" /> <div className="absolute inset-0 animate-spin rounded-full border-2" style={{ borderColor: ringColor, borderTopColor: "transparent", animationDuration: `${spinSpeed}s`, ...(reducedMotion && { animation: "none" }), }} /> </div> <div className="flex flex-col items-center gap-2"> <div className="text-6xl font-bold tabular-nums" style={{ color: ringColor }} > <span ref={counterRef}>{staticCount}</span>% </div> {showLabel && ( <p className="text-sm uppercase tracking-wider" style={{ color: `color-mix(in srgb, ${ringColor} 60%, transparent)`, }} > {label} </p> )} </div> </div> </div> ); }

Preloader

Controls

Install

Props

What It Demonstrates

Related Components

Refract

Pixel Transition

Border Glow

Spotlight Shell

Animated Hamburger

Morph Dialog

Appears In

Controls