Skeletons

Swap & anti-flash

The part most skeletons get wrong. Set latency to 120ms with the guard on and no skeleton appears at all; turn the guard off and watch it flicker.

  • cross-fade
  • flash
  • min-duration
  • hook

Preview

idle · skeleton hidden

Field notes

The two-hundred millisecond rule

A response that lands inside a fifth of a second feels instant, so showing a skeleton for it makes the interface feel slower than doing nothing at all. Wait, then commit.

Ada Lovelace

4 min read

Usage

const showSkeleton = useDeferredLoading(isFetching, { delay: 200, minDuration: 500 });

<SkeletonSwap loading={showSkeleton} skeleton={<SkeletonCard />}>
  <Article {...data} />
</SkeletonSwap>
"use client";

import { useEffect, useRef, useState } from "react";
import { cn } from "@/lib/cn";

export interface SkeletonSwapProps {
  loading: boolean;
  skeleton: React.ReactNode;
  children: React.ReactNode;
  /** Cross-fade duration in ms. */
  duration?: number;
  /** Animate the container height between the two states. */
  morphHeight?: boolean;
  className?: string;
}

/**
 * Cross-fades a skeleton into real content instead of hard-swapping it,
 * optionally easing the height difference so the page doesn't jump.
 */
export function SkeletonSwap({
  loading,
  skeleton,
  children,
  duration = 320,
  morphHeight = true,
  className,
}: SkeletonSwapProps) {
  const wrap = useRef<HTMLDivElement>(null);
  const active = useRef<HTMLDivElement>(null);
  const [height, setHeight] = useState<number | undefined>(undefined);

  useEffect(() => {
    if (!morphHeight || !active.current) return;
    const el = active.current;
    const measure = () => setHeight(el.offsetHeight);
    measure();
    const ro = new ResizeObserver(measure);
    ro.observe(el);
    return () => ro.disconnect();
  }, [loading, morphHeight]);

  return (
    <div
      ref={wrap}
      className={cn("relative w-full", className)}
      style={{
        height: morphHeight ? height : undefined,
        transition: morphHeight ? `height ${duration}ms var(--ease-out-quint)` : undefined,
      }}
    >
      <Layer visible={loading} duration={duration} ref={loading ? active : undefined}>
        {skeleton}
      </Layer>
      <Layer visible={!loading} duration={duration} ref={loading ? undefined : active}>
        {children}
      </Layer>
    </div>
  );
}

function Layer({
  visible,
  duration,
  children,
  ref,
}: {
  visible: boolean;
  duration: number;
  children: React.ReactNode;
  ref?: React.Ref<HTMLDivElement>;
}) {
  return (
    <div
      ref={ref}
      aria-hidden={!visible}
      className={cn("w-full", visible ? "relative" : "pointer-events-none absolute inset-x-0 top-0")}
      style={{
        opacity: visible ? 1 : 0,
        filter: visible ? "blur(0px)" : "blur(4px)",
        transition: `opacity ${duration}ms var(--ease-out-quint), filter ${duration}ms var(--ease-out-quint)`,
      }}
    >
      {children}
    </div>
  );
}

export default SkeletonSwap;