Shimmer

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

Drafting a reply…

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

pnpm dlx shadcn@latest add @arene/shimmer

Needs the arene setup first.

Usage

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

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

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

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

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

Trace merges base into the title of a running line itself, so a trace needs nothing from this page unless you tune the sweep.

KeyWhat it does
basePaints the text with a moving gradient and loops the sweep
oncePlays a single sweep instead of looping
reverseSweeps from right to left instead of left to right
noneTurns 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 that shows a live status while an assistant works.

Thinking…
Searching the docs
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:

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.

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.

Drafting a reply…

Drafting a reply…

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.

Drafting a reply…

2s

Drafting a reply…

1s

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.

Drafting a reply…

1rem

Drafting a reply…

6rem

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.

Drafting a reply…

20deg

Drafting a reply…

45deg

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.

Drafting a reply…

forward

Drafting a reply…

reverse

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.

Reply ready.

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

Drafting a reply…

"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

KeyDescription
baseThe gradient, background-clip: text, the transparent fill and the looping sweep
onceanimation-iteration-count: 1
reverseanimation-direction: reverse
noneRemoves the gradient and the animation and restores the text fill

CSS variables

They inherit. See Tuning for where to set them.

VariableDefaultEffect
--arene-shimmer-duration2sThe length of one sweep
--arene-shimmer-spreadcalc(3ch + 40px)The width of the highlight
--arene-shimmer-angle20degThe tilt of the band
--arene-shimmer-colorA light-dark() tint of currentColorThe highlight colour