tw-shimmer

Tailwind CSS v4 plugin for shimmer effects. Zero-dependency, CSS-only, with sine-eased gradients for buttery-smooth highlights and OKLCH color space for perceptually uniform color mixing. Provides text-shimmer and skeleton/background-shimmer variants with customizable speed, spread, angle, and colors.

Installation

npm install tw-shimmer

/* app/globals.css */
@import "tailwindcss";
@import "tw-shimmer";

Usage

Text shimmer keeps one text node. Where -webkit-mask-clip: text is supported, the host is masked and an additive highlight band moves on the compositor. Other browsers keep the existing gradient fallback.

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

<div class="shimmer-container space-y-2">
  <div class="shimmer shimmer-bg bg-gray-200 h-4 w-full rounded"></div>
  <div class="shimmer shimmer-bg bg-gray-200 h-4 w-3/4 rounded"></div>
</div>

Inside a shimmer-container, the plugin derives the track width from the container width. Because the container exposes only its inline size, the height term for angled gradients uses the nearest block-size query container when available and otherwise the small viewport height, with half the container width and 200px as minimums. Text shimmer hosts should contain text only: the host mask clips every descendant, including icons. Selection backgrounds are clipped to the glyphs on the compositor path.

The compositor highlight is additive. It defaults to white and --shimmer-color, including shimmer-color-*, overrides the band color. This matches the gradient on white and dark surfaces but can look different on tinted surfaces. shimmer-invert selects a black band.

Text shimmer holds still under prefers-reduced-motion: reduce on both paths, leaving the label in its plain text color. shimmer-bg keeps animating.

Utilities

| Utility | Effect | | ------------------------ | ----------------------------------------------------------------------------- | | shimmer | Base text shimmer. Pair with a low-opacity text color. | | shimmer-bg | Background shimmer; requires shimmer and a base bg-* class. | | shimmer-container | Parent container that sizes the animation track for children. | | shimmer-speed-{value} | Animation speed in px per second (text: 200, background: 1000 by default). | | --shimmer-track-width | Animation track width for timing (200px by default). | | shimmer-spread-{value} | Highlight thickness (text: calc(4ch + 80px), background: 480px by default). | | shimmer-angle-{value} | Highlight angle in degrees (15 by default). | | shimmer-repeat-delay-* | Pause between cycles in ms (text: 100, background: 20 by default). | | shimmer-color-{color} | Highlight color from your Tailwind palette. | | shimmer-invert | Use a contrasting additive highlight band. |

Variables are inheritable; set them on any ancestor element and descendants pick them up unless they override. The same speed, duration, repeat delay, angle, and track width drive both rendering paths.

Documentation

Full utility reference, accessibility notes, and the technical details of the sine-eased gradient pipeline at assistant-ui.com/tw-shimmer.