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