Text Shimmer
ProA short status label with a light that sweeps across it, for work that is still open.
Playground
Installation
Text Shimmer comes with WunderUI Core and Pro, in the package from your plan. See the plans.
Then import what you need:
import { TextShimmer } from "@wunderui/react"Then use it:
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 for
- Chat Loader for three dots when there is no label to show
- Spinner for a wait that is not the assistant's answer, such as a save
- Usage Meter for a measured value such as tokens or cost
Placement
Put the shimmer where the status belongs: alone, beside an icon, or in the assistant's bubble while a reply is pending. It is not announced by itself, so wrap it in a status region.
Size
The text is 14 px and medium by default. Pass a size class to match the line it sits in; the sweep scales with the text.
Newer props
Without props the shimmer takes the size and weight of its parent. Pass size and weight when it stands alone.
Inherited size, or size and weight props
Reading the contract…
Writing the summary…Behavior and motion
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 and 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
The figure marks the text. The shimmer has no other part: the light is the text's own background, clipped to the letters.
- 1
A span that takes the size and weight of its parent (or the and props). A gradient of the tertiary and foreground colours is clipped to the letters and sweeps across them every two seconds.
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
- Do
Pass a short string only. The shimmer reads best on a few words.
- Do
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.
- Do
Say the state in words, such as Reading 3 files. With reduced motion the sweep stops, so the text carries the meaning.
- Do
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
Don't use it for body text, a title or a button label. It is a status, not a style.
API reference
TextShimmer is a plain component, not a wrapper of a primitive. It takes the props below and no other element attributes.
A span that takes the size and weight of its parent (or the and props). A gradient of the tertiary and foreground colours is clipped to the letters and sweeps across them every two seconds.
| Prop | Type | Default | Description |
|---|---|---|---|
| children required | 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 or to change the size, or 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. |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("text-shimmer")The full library index for assistants is at /llms.txt.