Is the ai2 Skeleton compatible with shadcn/ui?

Yes. It has the same single-part anatomy as the shadcn/ui skeleton and installs through the standard shadcn registry format, so it drops into any shadcn/ui project and existing snippets keep working.

Is the skeleton accessible?

It renders a plain div with no ARIA attributes of its own, which is intentional: a placeholder has nothing to announce. For screen readers, put aria-hidden on the skeleton region, mark the loading container with aria-busy, and let the loaded content or a live region announce the result.

How do I install the ai2 Skeleton?

Run npx shadcn add @ai2/skeleton with the ai2 registry configured in components.json. An MCP agent can run the same install for you, or you can copy the source from this page manually.

Can an AI agent install and use this component?

Yes. The registry item ships agent-readable metadata and a working example, and the page provides a copy prompt. Point the shadcn MCP server at the @ai2 registry and the agent can search, inspect and install it on its own.

How do I change the skeleton's size and shape?

Use the shape prop (line, circle, rect) for the base geometry and Tailwind className like h-4 w-48 or size-10 for exact dimensions. line is h-4 w-full, circle is a rounded-full square, rect is a plain rounded block.

How is the animation implemented, and is there a shimmer?

The animation prop is pulse or none. pulse is Tailwind's animate-pulse, a pure CSS opacity animation; none renders a static block. There is deliberately no shimmer: a shimmer needs a CSS keyframe, and a registry theme item ships CSS variables only, so a keyframe cannot travel to consumers. Add one in your own globals if you need it.

Does the skeleton work in dark mode?

Yes. The fill color is the surface-3 token from the ai2 theme file, which resolves to the correct value in both light and dark mode automatically.

Skeleton or spinner, which should I use?

Use a skeleton when you know the shape of the incoming content, such as cards, lists and profiles. Use a spinner for indeterminate operations without a layout to mirror, such as a form submission.

Skeleton

A pulsing loading placeholder on the surface tokens - compose several to mirror the shape of the content that is loading.

displayfeedback

A free styled version is available

import { Skeleton } from "@/components/ui/skeleton"

export default function SkeletonDemo() {
  return (
    <div className="flex max-w-sm items-center gap-3">
      <Skeleton shape="circle" className="size-10" />
      <div className="flex flex-1 flex-col gap-2">
        <Skeleton shape="line" className="w-3/4" />
        <Skeleton shape="line" className="w-1/2" />
      </div>
    </div>
  )
}

Installation

Run the following command

npx shadcn@latest add @ai2/skeleton

The @ai2/tokens theme and the component file are installed together.

Add the cn util

lib/utils.ts

import { clsx, type ClassValue } from "clsx"
import { twMerge } from "tailwind-merge"

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

/* Adds a source-attribution ref param to a URL (the inspiration exports mark their
   outbound links with an ai2.design attribution). An invalid URL is returned as is.

   This file is SHOWN TO THE CONSUMER: the docs component pages render the source of
   `cn` in a code block, so a Turkish comment here would reach every one of those
   pages. Keep it English. */
export function withRef(url: string, ref = "ai2.design"): string {
  try {
    const u = new URL(url)
    u.searchParams.set("ref", ref)
    return u.toString()
  } catch {
    return url
  }
}

Copy the source code

components/ui/skeleton.tsx

import type * as React from "react"
import { cva, type VariantProps } from "class-variance-authority"

import { cn } from "@/lib/utils"

const skeletonVariants = cva("bg-surface-3", {
  variants: {
    shape: {
      line: "h-4 w-full rounded-md",
      circle: "aspect-square rounded-full",
      rect: "rounded-md",
    },
    animation: {
      pulse: "animate-pulse motion-reduce:animate-none",
      none: "",
    },
  },
  defaultVariants: { shape: "rect", animation: "pulse" },
})

interface SkeletonProps
  extends React.ComponentProps<"div">,
    VariantProps<typeof skeletonVariants> {}

function Skeleton({ className, shape, animation, ...props }: SkeletonProps) {
  return (
    <div
      data-slot="skeleton"
      className={cn(skeletonVariants({ shape, animation, className }))}
      {...props}
    />
  )
}

export { Skeleton, skeletonVariants, type SkeletonProps }

Manual installs skip the @ai2/tokens theme - add the token CSS from the theming guide or the surface colors will be missing.

Usage

import { Skeleton } from "@/components/ui/skeleton"

<Skeleton shape="line" className="w-48" />

Skeleton renders a pulsing <div> - width, height and shape come entirely from className.

Examples

Shapes

The shape prop sets the base geometry: line for text bars, circle for avatars and rect (the default) for media blocks. className refines the exact width, height and radius.

Animation

animation="pulse" (the default) uses Tailwind's animate-pulse; animation="none" renders a static block. There is deliberately no shimmer option: a shimmer needs a CSS keyframe, and a registry theme item cannot ship one, so add it in your own globals if you need it.

Card skeleton

Compose multiple Skeletons to mirror the layout of the loading content - matching shapes keep the swap from placeholder to content calm.

Props

Skeleton adds two axes on top of every native <div> prop; className still fine-tunes the exact size and radius.

Prop	Type	Default	Description
`shape`	`"line" \| "circle" \| "rect"`	`"rect"`	Base geometry. line is h-4 w-full, circle is a rounded-full square, rect is a plain rounded block. className fine-tunes size on top.
`animation`	`"pulse" \| "none"`	`"pulse"`	pulse uses Tailwind's animate-pulse; none renders a static block. There is deliberately no shimmer option.

ai2 Skeleton: loading placeholders for React, shaped by className

The ai2 Skeleton is a shadcn-compatible skeleton component for React, styled with Tailwind CSS v4. It renders a pulsing placeholder block that stands in for content while it loads: text lines, avatars, cards, table rows, whole page sections. The pulse and the fill color both come from the shared ai2 tokens, so placeholders match your theme in light and dark mode.

It ships through the shadcn registry format, so one CLI command, an MCP agent, or a copy-paste puts the source in your own project. You own the file; there is no runtime dependency on ai2 itself. The live example above is the exact component you get.

What is the ai2 Skeleton?

It is a single part: Skeleton, a plain <div> on the bg-surface-3 token. There is no radix primitive; a shape prop (line, circle, rect) and an animation prop (pulse, none) set the geometry and the pulse, and className fine-tunes width, height and radius on top. The anatomy stays shadcn/ui compatible, so existing snippets and AI agents keep working.

Because it is just a styled div, you compose loading states the same way you compose layouts: a circle for the avatar, bars for the text lines, a large rounded block for the media. Matching the real content's shape is what makes the swap from placeholder to data feel calm instead of jarring.

Why use it

Perceived performance: A skeleton that mirrors the incoming layout tells users what is coming and where, which reads faster than a spinner or a blank region.
Two simple axes: A shape prop (line, circle, rect) and an animation prop (pulse, none) cover the common cases, and Tailwind className handles every exact size on top.
Layout stability: Sizing the skeleton like the real content reserves the space up front, so the page does not shift when data arrives.
Theme-correct by default: The fill is the surface-3 token from the shared theme file, not a hardcoded gray, so placeholders look right in both light and dark mode.
Agent-readable metadata: The registry item describes the component and its intended use in plain words, so an MCP agent can find, inspect and install it without guessing.

Features

shadcn registry install: One command adds the component and the @ai2/tokens theme to your project. There are no npm dependencies beyond the cn util.
Pulse or none: The animation prop is pulse (Tailwind's animate-pulse, pure CSS) or none for a static block. There is deliberately no shimmer, since a keyframe cannot travel through a registry theme item.
Shape prop plus className: The shape prop gives you line, circle and rect out of the box, and className refines the exact width, height and radius on top.
Composable into full layouts: Stack several Skeletons in flex or grid wrappers to mirror an entire card, list row or page section while it loads.
Data attribute for styling: The element exposes data-slot="skeleton", so you can target every placeholder from CSS without forking the component.
TypeScript source: The file you install is typed and forwards every native div prop, including aria attributes and event handlers.

Production tips

Mirror the real layout: Copy the dimensions of the loaded state: same heights, widths and gaps. A skeleton that does not match the final layout causes a visible jump when content lands.
Hide skeletons from screen readers: The component ships no ARIA attributes of its own. Put aria-hidden="true" on the skeleton region and aria-busy="true" on the loading container, and announce the loaded state instead.
Vary the bar widths: Real text lines end at different points. Use w-3/4 and w-1/2 style widths on consecutive bars so the placeholder reads as text, not as stripes.
Do not skeleton everything: Reserve skeletons for content with a known shape. For indeterminate operations like a form submit, a spinner or a progress bar communicates better.
Keep it brief: Skeletons are for sub-second to few-second waits. If loading routinely takes longer, show real progress or partial data instead of an endless pulse.

Works with the rest of ai2

The skeleton composes naturally with the rest of the registry. Mirror an ai2 Avatar with a rounded-full circle, sketch an ai2 Card while its data loads, or fill ai2 Table rows with bars during a fetch.

For loading states without a fixed shape, pair it with the ai2 Spinner for indeterminate waits or ai2 Progress when you can report completion. Everything shares one token source, so loading and loaded states stay visually consistent in both modes.