tw-shimmer is a zero-dependency Tailwind CSS v4 plugin that provides polished shimmer animations for both text and skeleton loaders. It uses sine-eased gradients with 17 carefully calculated stops and OKLCH color mixing for smooth, banding-free effects.

• CSS-only — No JavaScript runtime, pure Tailwind utilities
• Text + Background — Shimmer text or skeleton placeholders
• Auto-sizing — CSS container queries for automatic width detection
• Customizable — Speed, spread, angle, color, and timing

See the interactive demo for live examples.

Installation#

<Tabs items={["npm", "pnpm", "yarn"]}>

sh npm install tw-shimmer


sh pnpm add tw-shimmer


sh yarn add tw-shimmer

Add to your CSS:

@import "tailwindcss";
@import "tw-shimmer";

Quick Start#

Text Shimmer#

<span class="shimmer text-foreground/60">Loading...</span>

Skeleton Loader#

<div class="shimmer shimmer-bg bg-muted h-4 w-48 rounded" />

Skeleton Card with Auto-Sizing#

<div class="shimmer-container flex gap-3">
  <div class="shimmer-bg bg-muted size-12 rounded-full" />
  <div class="flex-1 space-y-2">
    <div class="shimmer-bg bg-muted h-4 w-1/4 rounded" />
    <div class="shimmer-bg bg-muted h-4 w-full rounded" />
    <div class="shimmer-bg bg-muted h-4 w-4/5 rounded" />
  </div>
</div>

API Reference#

Core Utilities#

shimmer#

Base utility for text shimmer. Applies a gradient animation over the text foreground color.

shimmer-bg#

Background shimmer for skeleton loaders. Applies a gradient animation over the element's background. Requires a base bg-* class.

<div class="shimmer shimmer-bg bg-muted h-4 w-64 rounded" />

shimmer-container#

CSS-only auto-sizing helper using container queries. Sets container-type: inline-size and automatically derives speed and spread from the container width.

<div class="shimmer-container">
  <div class="shimmer-bg bg-muted h-4 w-full rounded" />
</div>

Customization Utilities#

All utilities are inheritable — set on a parent to affect all shimmer children.

Speed and Width#

Speed controls how fast the shimmer moves in pixels per second. Width tells the animation how wide the container is for timing calculations.

<span class="shimmer shimmer-speed-200 shimmer-width-400 text-foreground/40">
  Fast, wide shimmer
</span>

Color#

Use any Tailwind color with optional opacity:

<span class="shimmer shimmer-color-blue-500 text-blue-500/40">
  Blue shimmer
</span>

<div class="shimmer shimmer-bg shimmer-color-blue-300/30 bg-muted h-4 rounded" />

Angle#

Control the sweep direction. Default is 90deg (vertical sweep).

<div class="shimmer-container shimmer-angle-15">
  <div class="shimmer-bg bg-muted h-4 w-full rounded" />
</div>

Position Hints (Angled Shimmer)#

For angled shimmers, use shimmer-x-{n} and shimmer-y-{n} to sync elements:

<div class="shimmer-container shimmer-angle-15 flex gap-3">
  <div class="shimmer-bg shimmer-x-20 shimmer-y-20 bg-muted size-12 rounded-full" />
  <div class="flex-1 space-y-2">
    <div class="shimmer-bg shimmer-x-52 shimmer-y-0 bg-muted h-4 w-24 rounded" />
    <div class="shimmer-bg shimmer-x-52 shimmer-y-24 bg-muted h-4 w-full rounded" />
  </div>
</div>

Repeat Delay#

Control the pause between animation cycles:

<!-- Continuous shimmer, no pause -->
<span class="shimmer shimmer-repeat-delay-0 text-foreground/40">
  Always moving
</span>

<!-- Long pause between cycles -->
<span class="shimmer shimmer-repeat-delay-3000 text-foreground/40">
  Slow pulse
</span>

CSS Variables#

All values can be set via CSS variables for dynamic control:

<div style={{ "--shimmer-width": containerWidth } as React.CSSProperties}>
  <div className="shimmer shimmer-bg bg-muted h-4 w-full rounded" />
</div>

Browser Support#

Uses modern CSS features: oklch(), color-mix(), independent translate transform, and CSS Container Queries.

Supported: Chrome 111+, Firefox 113+, Safari 16.4+

Older browsers degrade gracefully — shimmer effects simply won't appear.