# Text Shimmer

A shimmering-gradient text effect for a 'thinking...' loading label.

- Category: AI & Agents
- Page: https://wunderui.com/components/text-shimmer
- Tier: Core and Pro

## Install

Text Shimmer ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { TextShimmer } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
import { TextShimmer } from "@wunderui/react"

export function Working({ working }: { working: boolean }) {
  return working ? (
    <div role="status">
      <TextShimmer>Thinking</TextShimmer>
    </div>
  ) : null
}
```

Expected result: The word Thinking in grey with a light that sweeps across it every two seconds. With reduced motion the word stands still.

## When to use

### Use Text Shimmer for

- A short status label while the assistant or an agent works, such as Thinking or Reading 3 files
- The pending bubble of a reply, before the first word arrives
- One open stage of a run, with the finished stages shown as plain text

### Use something else

- [Chat Loader](https://wunderui.com/components/chat-loader) for three dots when there is no label to show
- [Spinner](https://wunderui.com/components/spinner) for a wait that is not the assistant's answer, such as a save
- [Usage Meter](https://wunderui.com/components/usage-meter) for a measured value such as tokens or cost

## Behavior

What the shimmer does with its text, its loop and a screen reader.

- **Text only:** The shimmer takes a string only, no icon or element. Put an icon next to it in your own row, in the tertiary text colour.
- **Not announced:** The span announces nothing by itself. Wrap it in a status region, or put it in a live log, so the label is read once.
- **Meaning in words:** The sweep only says that something is running. Say the same in the label, such as Reading 3 files, so the state is clear without the motion.
- **One at a time:** The loop means in progress. Show one shimmer in a view and replace it with plain text as soon as the work ends.
- **Colour:** At rest the letters are tertiary text and the light is the foreground colour. Both follow the theme, so it works in light and dark.
- **Size:** The text inherits the size and weight of its parent. The `size` and `weight` props or a class set them, and the sweep scales with the text.
- **Motion:** A linear two-second loop moves the gradient across the letters. Nothing moves in the layout and the text doesn't shift.
- **Reduced motion:** With reduced motion the loop is off and the letters are static. The label stays and carries the status.

## Anatomy

- `TextShimmer`: A span that takes the size and weight of its parent (or the `size` and `weight` props). A gradient of the tertiary and foreground colours is clipped to the letters and sweeps across them every two seconds.
- `Label`: The text, passed as a string. It is the only content, and a screen reader reads it once when it appears inside a status region.

## Best practices

### When to use

- Use it for a short status while work is open. For a measured value use Usage Meter, and for the dots of a pending reply use Chat Loader.

### Do

- Pass a short string only. The shimmer reads best on a few words.
- Swap the shimmer for plain text as soon as the work ends, in success or failure. A loop that outlives the work lies about the state.
- Say the state in words, such as Reading 3 files. With reduced motion the sweep stops, so the text carries the meaning.
- Wrap it in a status region when nothing else announces the change.

### Don't

- Don't show more than one shimmer in a view. A running step may pulse, but nothing else should loop.
- Don't use it for body text, a title or a button label. It is a status, not a style.

## API reference

### TextShimmer

| Prop | Type | Default | Description |
|---|---|---|---|
| children* | string |  | The label. It must be a string, so the gradient can be clipped to it. Keep it to a few words. |
| className | string |  | Extra classes for the span, for example `text-base` or `text-xl` to change the size, or `font-semibold` for the weight. |
| size | "base" \| "lg" \| "sm" \| "xs" |  | Text size. Without it the shimmer inherits the size of its parent. |
| weight | "medium" \| "semibold" \| "normal" |  | Font weight. Without it the shimmer inherits the weight of its parent. |

## Examples

### Placement: on its own, beside an icon, in a message

### Size: 14, 16 and 20 px

### Inherited size, or size and weight props

## In context

### Run stages: one shimmer at a time

Press Start the run. The open stage shimmers, and when the next starts the finished one turns into plain text with a check; the last line says in words when the run ends.

### Pending reply: the shimmer gives way to the first word

Press Ask a question. The bubble shows Thinking with a shimmer, then the words stream in and the shimmer is removed.

## For AI agents

`get_component("text-shimmer")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
