Skeleton

An animated placeholder that holds a content's shape while it loads.

Usage

import { Skeleton } from '@appica/ui-react/skeleton'

<Skeleton className="h-4 w-40" />

Skeleton is a low-level placeholder block. It has no fixed size — you give it dimensions with ordinary utility classes (h-*/w-*/size-*) — and a gentle default rounded-md you can reshape with any rounded-* (rounded-full for a dot, rounded-[inherit] to match a parent's shape, or rounded-none to square it off). This keeps it composable: build a line, a circle, an avatar, or a whole card preview by stacking Skeletons, and they all inherit your design tokens automatically.

Its surface and shimmer highlight are both derived from currentColor, so a single text-* class recolors the whole placeholder coherently — the shimmer always matches the surface. By default it's a subtle tint of your foreground token.

Pick the animation with the effect prop — shimmer (default) glides a soft highlight across the block, pulse fades it in and out, and none renders a static placeholder. Both animations are skipped when the user prefers reduced motion.

Examples

Default

A single Skeleton with a height, width, and radius. The default shimmer effect glides a highlight derived from your foreground token, so it reads on both light and dark surfaces.

import { Skeleton } from '@appica/ui-react/skeleton'

export default function SkeletonDefault() {
  return <Skeleton className="h-28 w-64 rounded-xl" />
}

Effects

Switch the animation with effect. shimmer glides a highlight across the block, pulse fades the whole block, and none stays static — useful when you want the placeholder without motion.

shimmer

pulse

none

import { Skeleton } from '@appica/ui-react/skeleton'

export default function SkeletonEffects() {
  return (
    <div className="flex flex-wrap items-start justify-center gap-10">
      <div className="flex flex-col items-center gap-3">
        <Skeleton effect="shimmer" className="h-24 w-40 rounded-xl" />
        <span className="text-foreground-muted text-xs">shimmer</span>
      </div>
      <div className="flex flex-col items-center gap-3">
        <Skeleton effect="pulse" className="h-24 w-40 rounded-xl" />
        <span className="text-foreground-muted text-xs">pulse</span>
      </div>
      <div className="flex flex-col items-center gap-3">
        <Skeleton effect="none" className="h-24 w-40 rounded-xl" />
        <span className="text-foreground-muted text-xs">none</span>
      </div>
    </div>
  )
}

Composing shapes

There are no shape props. Reshape the same primitive with utility classes — rounded-full for an avatar, size-* for a square, a small h-*/w-* for a line.

import { Skeleton } from '@appica/ui-react/skeleton'

export default function SkeletonShapes() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-6">
      <Skeleton className="size-16 rounded-full" />
      <Skeleton className="size-16 rounded-xl" />
      <Skeleton className="h-10 w-32 rounded-lg" />
      <Skeleton className="h-4 w-40 rounded-full" />
    </div>
  )
}

Text lines

Stack a few full-width lines and taper the last ones with fractional widths (w-4/5, w-2/3) to mimic a paragraph.

import { Skeleton } from '@appica/ui-react/skeleton'

export default function SkeletonText() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-2.5">
      <Skeleton className="h-4 w-full" />
      <Skeleton className="h-4 w-full" />
      <Skeleton className="h-4 w-4/5" />
      <Skeleton className="h-4 w-2/3" />
    </div>
  )
}

Card

Compose placeholders into the layout you're loading — a media block, an avatar, and two text lines — so the skeleton matches the real content's footprint and there's no layout shift when it arrives.

import { Skeleton } from '@appica/ui-react/skeleton'

export default function SkeletonCard() {
  return (
    <div className="border-border bg-background w-full max-w-sm rounded-xl border p-4">
      <Skeleton className="aspect-video w-full rounded-lg" />
      <div className="mt-4 flex items-center gap-3">
        <Skeleton className="size-10 shrink-0 rounded-full" />
        <div className="flex flex-1 flex-col gap-2">
          <Skeleton className="h-3.5 w-2/3" />
          <Skeleton className="h-3 w-1/3" />
        </div>
      </div>
    </div>
  )
}

Recoloring

Surface and shimmer both come from currentColor, so one text-* class tints the whole placeholder and keeps the shimmer in sync with the surface. For a shimmer color independent of the surface, set the --skeleton-highlight custom property directly.

import { Skeleton } from '@appica/ui-react/skeleton'

export default function SkeletonColors() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-4">
      <Skeleton className="size-16 rounded-xl" />
      <Skeleton className="text-primary size-16 rounded-xl" />
      <Skeleton className="text-secondary-emphasis size-16 rounded-xl" />
      <Skeleton className="text-error-emphasis size-16 rounded-xl" />
      <Skeleton className="text-success-emphasis size-16 rounded-xl" />
      <Skeleton className="text-warning-emphasis size-16 rounded-xl" />
      <Skeleton className="text-info-emphasis size-16 rounded-xl" />
      <Skeleton className="size-16 rounded-xl text-violet-500" />
    </div>
  )
}

Swapping in content

Render skeletons while content is pending, then swap them for the real elements once it arrives. Here the avatar uses its built-in AvatarFallback to show a Skeleton until the photo loads, and onLoadingStatusChange reveals the name and role at the same moment — hit Reload to fetch a fresh copy and replay it. Matching each skeleton to its element's size keeps the layout stable across the transition.

'use client'

import { useState, useEffect } from 'react'
import { Skeleton } from '@appica/ui-react/skeleton'
import { Button } from '@appica/ui-react/button'
import { Avatar, AvatarImage, AvatarFallback } from '@appica/ui-react/avatar'
import { Reload } from '@appica/icons-react'

export default function SkeletonLoading() {
  const [src, setSrc] = useState<string>()
  const [loaded, setLoaded] = useState(false)
  const [nonce, setNonce] = useState(0)

  useEffect(() => {
    setLoaded(false)
    setSrc(undefined)
    // Demo only: defer the image ~2.5s so the loading skeletons stay visible.
    const id = setTimeout(() => setSrc(`/avatars/01.jpg?reload=${nonce}`), 2500)
    return () => clearTimeout(id)
  }, [nonce])

  return (
    <div className="flex w-full max-w-sm flex-col gap-4">
      <div className="flex justify-end">
        <Button size="sm" variant="outline" onClick={() => setNonce((n) => n + 1)} disabled={!loaded}>
          <Reload data-icon="start" />
          Reload
        </Button>
      </div>

      <div className="border-border bg-background flex items-center gap-3 rounded-xl border p-4">
        <Avatar size="lg" className="shrink-0 bg-transparent">
          <AvatarImage
            src={src}
            alt="Sarah Jenkins"
            onLoadingStatusChange={(status) => setLoaded(status === 'loaded')}
          />
          <AvatarFallback>
            <Skeleton className="size-full rounded-[inherit]" />
          </AvatarFallback>
        </Avatar>
        <div className="flex flex-1 flex-col gap-1.5">
          {loaded ? (
            <>
              <span className="text-foreground-intense -mb-0.5 text-sm font-semibold">Sarah Jenkins</span>
              <span className="text-foreground-muted text-xs">Product designer</span>
            </>
          ) : (
            <>
              <Skeleton className="h-4 w-2/3" />
              <Skeleton className="h-3 w-2/5" />
            </>
          )}
        </div>
      </div>
    </div>
  )
}

RTL

Every Appica UI component supports right-to-left layouts out of the box. Set the dir attribute on a container (commonly your <html> element) so CSS logical properties resolve correctly, and wrap your tree in DirectionProvider so direction-aware behavior follows the same direction.

import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}

Because skeletons are positioned with the same logical layout utilities as the content they stand in for, a placeholder card mirrors automatically — the avatar moves to the start (right) edge and the text lines follow. The shimmer sweep also reverses to travel right-to-left, following the reading direction.

API reference

Skeleton renders a <div>. Every other <div> attribute is forwarded, so className, style, and data attributes all pass straight through.

Prop	Type	Default	Description
`effect`	`'shimmer' \| 'pulse' \| 'none'`	`'shimmer'`	Animation played while the placeholder is visible. All effects honor `prefers-reduced-motion`.
`className`	`string`	—	Shape, color, and radius. A `text-` class recolors surface + shimmer; `rounded-`/`size-`/`h-`/`w-*` reshape.

The surface is currentColor at low opacity and the shimmer highlight is derived from currentColor too, so a single text-* class recolors both in step. The shimmer is also exposed as the --skeleton-highlight CSS custom property — set it on the element (e.g. [--skeleton-highlight:var(--primary)]) to retune the shimmer color independently of the surface.

Accessibility

A Skeleton is decorative — it renders with aria-hidden="true" so screen readers skip the placeholder geometry rather than announcing empty boxes.
For a loading region, announce the pending state on the container, not each block: set aria-busy="true" while data loads, and consider a polite live region (role="status") that reveals the content once it arrives.
Keep the skeleton's footprint close to the real content's so swapping it in causes no layout shift — a jump on load is its own accessibility problem.
All animations stop under prefers-reduced-motion: reduce (and the library's data-disable-animations escape hatch), leaving a static placeholder.

Actions & Inputs

Data Display

Decoration & Effects

Layout

Menus

Navigation

Overlays

Status & Feedback