# Shimmer

A style map that sweeps a highlight across text while it streams.

```tsx
import * as stylex from "@stylexjs/stylex"
import { textStyles } from "@/components/ui/text"
import { shimmerStyles } from "@/lib/shimmer"

export default function ShimmerDemo() {
  return (
    <p {...stylex.props(textStyles.sizes.sm, textStyles.tones.muted, shimmerStyles.base)}>
      Drafting a reply…
    </p>
  )
}
```

## Installation

**Command**

```bash
npx shadcn@latest add @arene/shimmer
```

Needs the [arene setup](https://www.arene.style/docs/installation) first.

**Manual**

1. Install the packages it imports:

   ```bash
   npm install @stylexjs/stylex
   ```

2. Set up the StyleX compiler, if you have not already. See
   [Installation](https://www.arene.style/docs/installation).

3. Paste this source into the file named in its title.

   ```ts title="lib/shimmer.ts"
   import * as stylex from "@stylexjs/stylex"

   const sweep = stylex.keyframes({
     from: { backgroundPosition: "100% 0" },
     to: { backgroundPosition: "0 0" },
   })

   const spread = "var(--arene-shimmer-spread, calc(3ch + 40px))"
   const highlight =
     "var(--arene-shimmer-color, light-dark(color-mix(in oklab, currentColor 20%, transparent), color-mix(in oklab, currentColor 40%, white)))"
   const blend = `color-mix(in oklab, ${highlight}, currentColor 50%)`

   const band = [
     `currentColor calc(50% - ${spread})`,
     `${blend} calc(50% - ${spread} * 0.5)`,
     `${highlight} 50%`,
     `${blend} calc(50% + ${spread} * 0.5)`,
     `currentColor calc(50% + ${spread})`,
   ].join(", ")

   export const shimmerStyles = stylex.create({
     base: {
       backgroundImage: {
         default: `linear-gradient(calc(90deg + var(--arene-shimmer-angle, 20deg)), ${band})`,
         "@media (prefers-reduced-motion: reduce)": "none",
       },
       backgroundRepeat: "no-repeat",
       backgroundSize: `calc(200% + ${spread} * 2) 100%`,
       backgroundPosition: "0 0",
       backgroundClip: "text",
       WebkitBackgroundClip: "text",
       WebkitTextFillColor: {
         default: "transparent",
         "@media (prefers-reduced-motion: reduce)": "currentColor",
       },
       animationName: { default: sweep, "@media (prefers-reduced-motion: reduce)": "none" },
       animationDuration: "var(--arene-shimmer-duration, 2s)",
       animationTimingFunction: "linear",
       animationIterationCount: "infinite",
     },
     once: { animationIterationCount: 1 },
     reverse: { animationDirection: "reverse" },
     none: {
       backgroundImage: "none",
       WebkitTextFillColor: "currentColor",
       animationName: "none",
     },
   })
   ```

4. Change the `@/` imports if your project uses different aliases.

## Usage

```tsx
import { shimmerStyles } from "@/lib/shimmer"
```

Merge `shimmerStyles.base` into the `stylex.props()` call of a text element.

```tsx
<p {...stylex.props(styles.text, shimmerStyles.base)}>Drafting a reply…</p>
```

On a arene component, pass it through `xstyle`, which the component merges
last.

```tsx
<MarkerContent xstyle={shimmerStyles.base}>Thinking…</MarkerContent>
```

[Trace](https://www.arene.style/docs/components/trace) merges `base` into the title of a running line
itself, so a trace needs nothing from this page unless you tune the sweep.

| Key       | What it does                                                |
| --------- | ----------------------------------------------------------- |
| `base`    | Paints the text with a moving gradient and loops the sweep  |
| `once`    | Plays a single sweep instead of looping                     |
| `reverse` | Sweeps from right to left instead of left to right          |
| `none`    | Turns the effect off and renders the text in its own colour |

The gradient is built from `currentColor`, so the shimmer takes the element's
text colour, from `mutedForeground` to a status colour, with nothing to set.
The highlight is a `light-dark()` pair: a faded copy of the text colour in the
light scheme, and a brighter one in the dark scheme, so it stays visible on a
dark background. The gradient fills the glyphs through `background-clip: text`,
and an animation on `background-position` moves the highlight across them.

`once`, `reverse` and `none` change `base`, so merge them after it.

## With Marker

The shimmer works on any element that renders text. A common use is a
[Marker](https://www.arene.style/docs/components/marker) that shows a live status while an assistant
works.

```tsx
import { Marker, MarkerContent } from "@/components/ui/marker"
import { VStack } from "@/components/ui/stack"
import { shimmerStyles } from "@/lib/shimmer"
import { widths } from "@/theme/widths"

export default function MarkerShimmer() {
  return (
    <VStack gap={8} xstyle={widths.sm}>
      <Marker role="status">
        <MarkerContent xstyle={shimmerStyles.base}>Thinking…</MarkerContent>
      </Marker>
      <Marker variant="separator" role="status">
        <MarkerContent xstyle={shimmerStyles.base}>Searching the docs</MarkerContent>
      </Marker>
    </VStack>
  )
}
```

## Tuning

Four custom properties tune the sweep: colour, duration, spread and angle. They
inherit, so set them on the shimmering element or on any element above it, such
as the list around a set of lines.

On an element you style yourself, put them in an entry merged into the same
`stylex.props()` call as `base`:

```tsx
const styles = stylex.create({
  slow: { "--arene-shimmer-duration": "3s" },
})

<p {...stylex.props(styles.text, shimmerStyles.base, styles.slow)}>…</p>
```

On a arene component, set them with `style`, cast to `CSSProperties`. `xstyle`
rejects a StyleX entry that sets only custom properties, because StyleX types
it as having nothing in common with CSS properties.

```tsx
const slow = { "--arene-shimmer-duration": "3s" } as CSSProperties

<Trace style={slow}>…</Trace>
```

## Color

Set `--arene-shimmer-color` to pick the highlight colour. The default is
derived from the text colour.

```tsx
import * as stylex from "@stylexjs/stylex"
import { VStack } from "@/components/ui/stack"
import { textStyles } from "@/components/ui/text"
import { shimmerStyles } from "@/lib/shimmer"
import { color } from "@/theme/tokens.stylex"

const styles = stylex.create({
  info: { "--arene-shimmer-color": `color-mix(in oklab, ${color.info} 60%, transparent)` },
  success: { "--arene-shimmer-color": color.success },
})

export default function ShimmerColor() {
  return (
    <VStack align="center" gap={2}>
      <p
        {...stylex.props(
          textStyles.sizes.sm,
          textStyles.tones.muted,
          shimmerStyles.base,
          styles.info,
        )}
      >
        Drafting a reply…
      </p>
      <p
        {...stylex.props(
          textStyles.sizes.sm,
          textStyles.tones.muted,
          shimmerStyles.base,
          styles.success,
        )}
      >
        Drafting a reply…
      </p>
    </VStack>
  )
}
```

## Duration

Set `--arene-shimmer-duration` to the length of one sweep. The default is
`2s`.

```tsx
import * as stylex from "@stylexjs/stylex"
import { Grid } from "@/components/ui/grid"
import { VStack } from "@/components/ui/stack"
import { textStyles } from "@/components/ui/text"
import { shimmerStyles } from "@/lib/shimmer"
import { color, font, leading, text } from "@/theme/tokens.stylex"
import { widths } from "@/theme/widths"

const styles = stylex.create({
  label: {
    color: color.mutedForeground,
    fontFamily: font.mono,
    fontSize: text.xs,
    lineHeight: leading.xs,
  },
  fast: { "--arene-shimmer-duration": "1s" },
})

const samples = [
  { label: "2s", tuning: null },
  { label: "1s", tuning: styles.fast },
]

export default function ShimmerDuration() {
  return (
    <Grid columns={2} gap={6} xstyle={widths.lg}>
      {samples.map(({ label, tuning }) => (
        <VStack key={label} align="center" gap={3}>
          <p
            {...stylex.props(
              textStyles.sizes.sm,
              textStyles.tones.muted,
              shimmerStyles.base,
              tuning,
            )}
          >
            Drafting a reply…
          </p>
          <p {...stylex.props(styles.label)}>{label}</p>
        </VStack>
      ))}
    </Grid>
  )
}
```

## Spread

Set `--arene-shimmer-spread` to the width of the highlight band. The default
is `calc(3ch + 40px)`. The `40px` part is fixed, and the `3ch` part scales with
the font size.

```tsx
import * as stylex from "@stylexjs/stylex"
import { Grid } from "@/components/ui/grid"
import { VStack } from "@/components/ui/stack"
import { textStyles } from "@/components/ui/text"
import { shimmerStyles } from "@/lib/shimmer"
import { color, font, leading, space, text } from "@/theme/tokens.stylex"
import { widths } from "@/theme/widths"

const styles = stylex.create({
  label: {
    color: color.mutedForeground,
    fontFamily: font.mono,
    fontSize: text.xs,
    lineHeight: leading.xs,
  },
  narrow: { "--arene-shimmer-spread": space.s4 },
  wide: { "--arene-shimmer-spread": space.s24 },
})

const samples = [
  { label: "1rem", tuning: styles.narrow },
  { label: "6rem", tuning: styles.wide },
]

export default function ShimmerSpread() {
  return (
    <Grid columns={2} gap={6} xstyle={widths.lg}>
      {samples.map(({ label, tuning }) => (
        <VStack key={label} align="center" gap={3}>
          <p
            {...stylex.props(
              textStyles.sizes.sm,
              textStyles.tones.muted,
              shimmerStyles.base,
              tuning,
            )}
          >
            Drafting a reply…
          </p>
          <p {...stylex.props(styles.label)}>{label}</p>
        </VStack>
      ))}
    </Grid>
  )
}
```

## Angle

Set `--arene-shimmer-angle` to tilt the band. The default is `20deg`.

```tsx
import * as stylex from "@stylexjs/stylex"
import { Grid } from "@/components/ui/grid"
import { VStack } from "@/components/ui/stack"
import { textStyles } from "@/components/ui/text"
import { shimmerStyles } from "@/lib/shimmer"
import { color, font, leading, text } from "@/theme/tokens.stylex"
import { widths } from "@/theme/widths"

const styles = stylex.create({
  label: {
    color: color.mutedForeground,
    fontFamily: font.mono,
    fontSize: text.xs,
    lineHeight: leading.xs,
  },
  steep: { "--arene-shimmer-angle": "45deg" },
})

const samples = [
  { label: "20deg", tuning: null },
  { label: "45deg", tuning: styles.steep },
]

export default function ShimmerAngle() {
  return (
    <Grid columns={2} gap={6} xstyle={widths.lg}>
      {samples.map(({ label, tuning }) => (
        <VStack key={label} align="center" gap={3}>
          <p
            {...stylex.props(
              textStyles.sizes.sm,
              textStyles.tones.muted,
              shimmerStyles.base,
              tuning,
            )}
          >
            Drafting a reply…
          </p>
          <p {...stylex.props(styles.label)}>{label}</p>
        </VStack>
      ))}
    </Grid>
  )
}
```

## Reverse

The highlight sweeps from left to right. Merge `shimmerStyles.reverse` to sweep
from right to left. arene assumes a left-to-right layout, so in a
right-to-left one, merge `reverse` to make the sweep follow the text.

```tsx
import * as stylex from "@stylexjs/stylex"
import { Grid } from "@/components/ui/grid"
import { VStack } from "@/components/ui/stack"
import { textStyles } from "@/components/ui/text"
import { shimmerStyles } from "@/lib/shimmer"
import { color, font, leading, text } from "@/theme/tokens.stylex"
import { widths } from "@/theme/widths"

const styles = stylex.create({
  label: {
    color: color.mutedForeground,
    fontFamily: font.mono,
    fontSize: text.xs,
    lineHeight: leading.xs,
  },
})

const samples = [
  { label: "forward", tuning: null },
  { label: "reverse", tuning: shimmerStyles.reverse },
]

export default function ShimmerReverse() {
  return (
    <Grid columns={2} gap={6} xstyle={widths.lg}>
      {samples.map(({ label, tuning }) => (
        <VStack key={label} align="center" gap={3}>
          <p
            {...stylex.props(
              textStyles.sizes.sm,
              textStyles.tones.muted,
              shimmerStyles.base,
              tuning,
            )}
          >
            Drafting a reply…
          </p>
          <p {...stylex.props(styles.label)}>{label}</p>
        </VStack>
      ))}
    </Grid>
  )
}
```

## Play once

Merge `shimmerStyles.once` to play a single sweep, as a reveal when streaming
finishes. Set `--arene-shimmer-duration` to control how long it takes. The
demo remounts the text to replay it.

```tsx
"use client"

import { useState } from "react"
import * as stylex from "@stylexjs/stylex"
import { Button } from "@/components/ui/button"
import { VStack } from "@/components/ui/stack"
import { textStyles } from "@/components/ui/text"
import { shimmerStyles } from "@/lib/shimmer"

const styles = stylex.create({
  reveal: { "--arene-shimmer-duration": "1.1s" },
})

export default function ShimmerOnce() {
  const [run, setRun] = useState(0)

  return (
    <VStack align="center" gap={4}>
      <p
        key={run}
        {...stylex.props(
          textStyles.sizes.sm,
          textStyles.tones.muted,
          shimmerStyles.base,
          shimmerStyles.once,
          styles.reveal,
        )}
      >
        Reply ready.
      </p>
      <Button variant="outline" size="sm" onClick={() => setRun((value) => value + 1)}>
        Replay
      </Button>
    </VStack>
  )
}
```

## Turning it off

Merge `shimmerStyles.none` conditionally to stop the effect, for example when a
response finishes streaming.

```tsx
"use client"

import { useState } from "react"
import * as stylex from "@stylexjs/stylex"
import { Button } from "@/components/ui/button"
import { VStack } from "@/components/ui/stack"
import { textStyles } from "@/components/ui/text"
import { shimmerStyles } from "@/lib/shimmer"

export default function ShimmerNone() {
  const [done, setDone] = useState(false)

  return (
    <VStack align="center" gap={4}>
      <p
        {...stylex.props(
          textStyles.sizes.sm,
          textStyles.tones.muted,
          shimmerStyles.base,
          done && shimmerStyles.none,
        )}
      >
        {done ? "Reply ready." : "Drafting a reply…"}
      </p>
      <Button variant="outline" size="sm" onClick={() => setDone((value) => !value)}>
        {done ? "Restart" : "Finish"}
      </Button>
    </VStack>
  )
}
```

## Reduced motion

When the user prefers reduced motion, `base` drops the gradient and the
animation, and the text renders in its own colour. This needs no setup.

## API reference

### shimmerStyles

| Key       | Description                                                                       |
| --------- | --------------------------------------------------------------------------------- |
| `base`    | The gradient, `background-clip: text`, the transparent fill and the looping sweep |
| `once`    | `animation-iteration-count: 1`                                                    |
| `reverse` | `animation-direction: reverse`                                                    |
| `none`    | Removes the gradient and the animation and restores the text fill                 |

### CSS variables

They inherit. See [Tuning](#tuning) for where to set them.

| Variable                   | Default                                 | Effect                     |
| -------------------------- | --------------------------------------- | -------------------------- |
| `--arene-shimmer-duration` | `2s`                                    | The length of one sweep    |
| `--arene-shimmer-spread`   | `calc(3ch + 40px)`                      | The width of the highlight |
| `--arene-shimmer-angle`    | `20deg`                                 | The tilt of the band       |
| `--arene-shimmer-color`    | A `light-dark()` tint of `currentColor` | The highlight colour       |
