# shimmer

Utilities for adding a shimmer effect to text elements.

Source: https://webjs.dev/ui/docs/utils/shimmer

```ts
import { html } from '@webjsdev/core';

export default function ShimmerDemo() {
  return html`
    <p class="shimmer text-sm text-muted-foreground">Generating response&hellip;</p>
  `;
}
```

## Installation

`shimmer` ships in `shadcn-tailwind.css`, the kit's shared Tailwind stylesheet of utilities and variants. It lives in the `@webjsdev/ui` package at `packages/registry/styles/shadcn-tailwind.css`, which a WebJs app has through the WebJs CLI. `webjs ui init` does not copy it into your app yet, so copy it next to your stylesheet:

```bash
cp node_modules/@webjsdev/ui/packages/registry/styles/shadcn-tailwind.css styles/
```

Then import it after Tailwind in your global CSS file:

```css
@import "tailwindcss";
@import "./shadcn-tailwind.css";
```

## Usage

| Class | Styles |
| --- | --- |
| `shimmer` | `background-clip: text;` `animation: tw-shimmer var(--shimmer-duration, 2s) linear infinite;` |
| `shimmer-once` | `animation-iteration-count: 1;` |
| `shimmer-reverse` | `animation-direction: reverse;` |
| `shimmer-none` | `--shimmer-image: none;` `--shimmer-text-fill: currentColor;` |
| `shimmer-color-<color>` | `--shimmer-color: <color>;` |
| `shimmer-color-[<value>]` | `--shimmer-color: <value>;` |
| `shimmer-color-<color>/<pct>` | `--shimmer-color: color-mix(in oklch, <color> <pct>, transparent);` |
| `shimmer-duration-<number>` | `--shimmer-duration: calc(<number> * 1ms);` |
| `shimmer-spread-<number>` | `--shimmer-spread: calc(var(--spacing) * <number>);` |
| `shimmer-spread-[<value>]` | `--shimmer-spread: <value>;` |
| `shimmer-angle-<number>` | `--shimmer-angle: calc(<number> * 1deg);` |

Add `shimmer` to a text element.

```html
<p class="shimmer text-muted-foreground">Generating response&hellip;</p>
```

The shimmer is built on `currentColor`, so it adapts to the element:

- The highlight is derived from the text color, with no configuration needed.
- It works on any color, from `text-muted-foreground` to brand colors.
- In dark mode, the highlight automatically brightens to stay visible.

The effect is pure CSS. The text is painted with `background-clip: text`, and the highlight sweeps across it in a seamless loop.

## With Marker

The shimmer composes with any component that renders text. A common pattern is a [Marker](https://webjs.dev/ui/docs/components/marker) showing a live status while the assistant is working:

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { markerClass, markerContentClass, markerIconClass } from '#components/ui/marker.ts';
import { spinner } from '#components/ui/spinner.ts';

export default function ShimmerMarker() {
  return html`
    <div class="flex w-full max-w-sm flex-col gap-4">
      <div data-slot="marker" data-variant="default" role="status" class=${markerClass()}>
        <span data-slot="marker-icon" aria-hidden="true" class=${markerIconClass()}>
          ${spinner({ decorative: true })}
        </span>
        <span data-slot="marker-content" class=${cn(markerContentClass(), 'shimmer')}>Thinking...</span>
      </div>
      <div data-slot="marker" data-variant="separator" role="status" class=${markerClass({ variant: 'separator' })}>
        <span data-slot="marker-content" class=${cn(markerContentClass(), 'shimmer')}>Reading 4 files</span>
      </div>
    </div>
  `;
}
```

```html
<div data-slot="marker" role="status" class=${markerClass()}>
  <span data-slot="marker-icon" aria-hidden="true" class=${markerIconClass()}>
    ${spinner({ decorative: true })}
  </span>
  <span data-slot="marker-content" class=${cn(markerContentClass(), 'shimmer')}>Thinking&hellip;</span>
</div>
```

## Color

Use `shimmer-color-<color>` to set the highlight color explicitly. It accepts theme colors with an optional opacity modifier, or any arbitrary color value.

```ts
import { html } from '@webjsdev/core';

export default function ShimmerColor() {
  return html`
    <div class="flex flex-col items-center gap-2 text-sm text-muted-foreground">
      <p class="shimmer shimmer-color-blue-500/60">Generating response&hellip;</p>
      <p class="shimmer shimmer-color-[#378ADD]">Generating response&hellip;</p>
    </div>
  `;
}
```

```html
<p class="shimmer shimmer-color-blue-500/60">Generating response&hellip;</p>
<p class="shimmer shimmer-color-[#378ADD]">Generating response&hellip;</p>
```

## Duration

Use `shimmer-duration-<number>` to set the duration of one sweep in milliseconds. The default is `2000`, i.e. `2s`.

```ts
import { html } from '@webjsdev/core';

export default function ShimmerDuration() {
  return html`
    <div class="mx-auto grid w-full max-w-lg gap-6 text-center text-sm text-muted-foreground sm:grid-cols-2">
      <div class="flex flex-col gap-3">
        <p class="shimmer">Generating response&hellip;</p>
        <p class="font-mono text-xs">shimmer</p>
      </div>
      <div class="flex flex-col gap-3">
        <p class="shimmer shimmer-duration-1000">Generating response&hellip;</p>
        <p class="font-mono text-xs">shimmer-duration-1000</p>
      </div>
    </div>
  `;
}
```

```html
<p class="shimmer shimmer-duration-1000">Generating response&hellip;</p>
```

## Spread

Use `shimmer-spread-<number>` to set the width of the highlight band using the spacing scale. The default is `calc(3ch + 40px)`, a fixed base plus a `3ch` term that scales with the font size.

```ts
import { html } from '@webjsdev/core';

export default function ShimmerSpread() {
  return html`
    <div class="mx-auto grid w-full max-w-lg gap-6 text-center text-sm text-muted-foreground sm:grid-cols-2">
      <div class="flex flex-col gap-3">
        <p class="shimmer shimmer-spread-4">Generating response&hellip;</p>
        <p class="font-mono text-xs">shimmer-spread-4</p>
      </div>
      <div class="flex flex-col gap-3">
        <p class="shimmer shimmer-spread-24">Generating response&hellip;</p>
        <p class="font-mono text-xs">shimmer-spread-24</p>
      </div>
    </div>
  `;
}
```

```html
<p class="shimmer shimmer-spread-24">Generating response&hellip;</p>
```

For one-off values, use an arbitrary length or percentage:

```html
<p class="shimmer shimmer-spread-[5rem]">Generating response&hellip;</p>
```

## Angle

Use `shimmer-angle-<number>` to set the tilt of the highlight band in degrees. The default is `20`.

```ts
import { html } from '@webjsdev/core';

export default function ShimmerAngle() {
  return html`
    <div class="mx-auto grid w-full max-w-lg gap-6 text-center text-sm text-muted-foreground sm:grid-cols-2">
      <div class="flex flex-col gap-3">
        <p class="shimmer">Generating response&hellip;</p>
        <p class="font-mono text-xs">shimmer</p>
      </div>
      <div class="flex flex-col gap-3">
        <p class="shimmer shimmer-angle-45">Generating response&hellip;</p>
        <p class="font-mono text-xs">shimmer-angle-45</p>
      </div>
    </div>
  `;
}
```

```html
<p class="shimmer shimmer-angle-45">Generating response&hellip;</p>
```

## Reverse

Use `shimmer-reverse` to sweep the highlight in the opposite direction. In RTL layouts the sweep already follows the reading direction. See RTL.

```html
<p class="shimmer shimmer-reverse">Generating response&hellip;</p>
```

## Play Once

Use `shimmer-once` to play a single sweep instead of looping, useful as a reveal when streaming completes. Pair it with `shimmer-duration-<number>` to control how long the sweep takes. The Replay button below toggles a checkbox that swaps two copies of the text, since an element that becomes visible starts its animation over.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';

// Replay without script: the checkbox swaps which of two copies is shown, and
// an element going from display:none to shown starts its animation over.
export default function ShimmerOnce() {
  return html`
    <div class="flex flex-col items-center gap-4">
      <input type="checkbox" id="shimmer-once-replay" class="peer sr-only">
      <p class="shimmer text-sm text-muted-foreground shimmer-duration-1100 shimmer-once peer-checked:hidden">Generating response&hellip;</p>
      <p class="hidden shimmer text-sm text-muted-foreground shimmer-duration-1100 shimmer-once peer-checked:block">Generating response&hellip;</p>
      <label for="shimmer-once-replay" data-slot="button" data-variant="outline" data-size="sm" class=${cn(buttonClass({ variant: 'outline', size: 'sm' }), 'peer-focus-visible:border-ring peer-focus-visible:ring-[3px] peer-focus-visible:ring-ring/50')}>Replay</label>
    </div>
  `;
}
```

```html
<p class="shimmer shimmer-duration-1100 shimmer-once">
  Response generated.
</p>
```

## Disabling the Shimmer

Use `shimmer-none` to turn the effect off and render the text normally. It works in any class order, so the typical use is responsive or stateful:

```ts
import { html } from '@webjsdev/core';

export default function ShimmerNone() {
  return html`
    <div class="flex flex-col items-center gap-3 text-sm text-muted-foreground">
      <p class="shimmer md:shimmer-none">Generating response&hellip;</p>
      <p class="font-mono text-xs">shimmer md:shimmer-none</p>
    </div>
  `;
}
```

```html
<p class="shimmer md:shimmer-none">Generating response&hellip;</p>
```

## Fallback

The shimmer is built on modern color features, [relative color syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_colors/Relative_colors) and `color-mix()`, which are available in all current browsers. In older browsers without support, the highlight gradient is dropped and the text can render transparent. If you target older browsers, apply `shimmer` conditionally with a `supports-*` variant:

```html
<p class="supports-[color:oklch(from_white_l_c_h)]:shimmer">
  Generating response&hellip;
</p>
```

## Reduced Motion

When the user prefers reduced motion, the animation is disabled automatically and the text renders normally.

## RTL

To enable RTL support in WebJs UI, see the [RTL configuration guide](https://webjs.dev/ui/docs/rtl).

The sweep follows the reading direction, left to right in LTR and right to left in RTL, with no extra classes. Use `shimmer-reverse` to flip the direction manually.

```ts
import { html } from '@webjsdev/core';

export default function ShimmerRtl() {
  return html`
    <div class="mx-auto grid w-full max-w-lg gap-6 text-center text-sm text-muted-foreground sm:grid-cols-2">
      <div class="flex flex-col gap-3">
        <p dir="ltr" class="shimmer">Generating response&hellip;</p>
        <p class="font-mono text-xs">dir="ltr"</p>
      </div>
      <div class="flex flex-col gap-3">
        <p dir="rtl" lang="ar" class="shimmer">جارٍ إنشاء الرد&hellip;</p>
        <p class="font-mono text-xs">dir="rtl"</p>
      </div>
    </div>
  `;
}
```
