Skeletons

Skeleton

The base placeholder. One element, four animation styles, three shapes — everything else in this category composes it.

  • placeholder
  • loading
  • primitive

Preview

line
rect
circle

Usage

<Skeleton animation="shimmer" shape="rect" height={96} />
import { cn } from "@/lib/cn";

export type SkeletonAnimation = "pulse" | "shimmer" | "wave" | "glow" | "none";
export type SkeletonShape = "line" | "circle" | "rect";

export interface SkeletonProps extends React.HTMLAttributes<HTMLDivElement> {
  /** How the placeholder animates while content loads. */
  animation?: SkeletonAnimation;
  shape?: SkeletonShape;
  width?: number | string;
  height?: number | string;
  /** Border radius override; ignored for `circle`. */
  radius?: number | string;
  /** Stagger offset in ms — lets a group ripple instead of blinking in unison. */
  delay?: number;
}

const base = "relative overflow-hidden bg-skeleton";

const shapes: Record<SkeletonShape, string> = {
  line: "h-3 w-full rounded-full",
  circle: "rounded-full aspect-square",
  rect: "rounded-lg",
};

export function Skeleton({
  animation = "shimmer",
  shape = "line",
  width,
  height,
  radius,
  delay = 0,
  className,
  style,
  ...rest
}: SkeletonProps) {
  const isShimmer = animation === "shimmer";

  return (
    <div
      aria-hidden
      data-slot="skeleton"
      className={cn(
        base,
        shapes[shape],
        animation === "pulse" && "animate-pulse",
        animation === "glow" && "animate-breathe",
        isShimmer &&
          "animate-shimmer bg-[linear-gradient(90deg,var(--color-skeleton)_25%,var(--color-skeleton-hi)_50%,var(--color-skeleton)_75%)] bg-[length:200%_100%]",
        className,
      )}
      style={{
        width,
        height,
        borderRadius: shape === "circle" ? undefined : radius,
        animationDelay: delay ? `${delay}ms` : undefined,
        ...style,
      }}
      {...rest}
    >
      {animation === "wave" && <WaveOverlay delay={delay} />}
    </div>
  );
}

function WaveOverlay({ delay }: { delay: number }) {
  return (
    <span
      className="absolute inset-0 animate-wave bg-[linear-gradient(90deg,transparent,var(--color-skeleton-hi),transparent)]"
      style={{ animationDelay: `${delay}ms` }}
    />
  );
}

export default Skeleton;