# tw-shimmer
URL: /docs/utilities/tw-shimmer

Tailwind CSS v4 plugin for shimmer effects.

> For AI agents: a documentation index is available at [llms.txt](/llms.txt). Use `.md` for canonical markdown pages; `.mdx` is kept as a backwards-compatible alias on supported URL paths.

`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](/tw-shimmer) for live examples.

## Installation

Choose one:

**npm**

```
npm install tw-shimmer
```

**pnpm**

```
pnpm add tw-shimmer
```

**yarn**

```
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>
```

> [!info]
>
> Set a semi-transparent text color (e.g., `text-foreground/40`) for the shimmer highlight to be visible.

### 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>
```

> [!warn]
>
> `shimmer-container` sets `container-type: inline-size`, which prevents shrink-to-fit sizing. Not recommended for text-only containers.

### Customization Utilities

| Utility                     | Default (text) | Default (bg) | Description                        |
| --------------------------- | -------------- | ------------ | ---------------------------------- |
| `shimmer-speed-{n}`         | `150`          | `1000`       | Animation speed in px/s            |
| `shimmer-width-{n}`         | `200`          | `800`        | Container width in px for timing   |
| `shimmer-spread-{n}`        | `6ch`          | —            | Text shimmer highlight width       |
| `shimmer-bg-spread-{n}`     | —              | `480px`      | Background shimmer highlight width |
| `shimmer-color-{color}`     | auto           | auto         | Highlight color (Tailwind palette) |
| `shimmer-angle-{deg}`       | `90`           | `90`         | Sweep direction in degrees         |
| `shimmer-duration-{ms}`     | auto           | auto         | Fixed animation duration           |
| `shimmer-repeat-delay-{ms}` | `1000`         | `1000`       | Pause between cycles               |
| `shimmer-invert`            | —              | —            | Invert highlight direction         |

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>
```

> [!warn]
>
> Avoid exactly `0deg` and `180deg` — they cause extreme animation delays. Safe range: 15-75° or 105-165°.

### 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:

| Variable                 | Description               |
| ------------------------ | ------------------------- |
| `--shimmer-speed`        | Speed in px/s             |
| `--shimmer-width`        | Track width in px         |
| `--shimmer-spread`       | Highlight width           |
| `--shimmer-angle`        | Sweep angle               |
| `--shimmer-color`        | Highlight color           |
| `--shimmer-duration`     | Override duration (ms)    |
| `--shimmer-repeat-delay` | Pause between cycles (ms) |

```
<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.