# textShimmer

> Sweeping highlight through a run of text's own glyphs for a caption that stands in for a busy state.

```ts
import { textShimmer } from "@sdxc/ui/animations";
```

Sweeping highlight through a run of text's own glyphs for a caption that
stands in for a busy state. The `background-clip: text` paint sits behind
an `@supports` guard; reduced motion breathes the caption's opacity.

## Signature

```ts
textShimmer<Node extends Element = Element>(options?: TextShimmer.Options): Mixin<Node>
```

Returns: A `@sdxc/u` mixin ready for a caption's host text element.

## Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `options?` | `TextShimmer.Options` | Timing, band width, angle, color, and gating for the loop. |

## Examples

```tsx
<Text mix={[textShimmer()]}>{t("chat.generating")}</Text>
```

```tsx
<Text mix={[textShimmer({ color: "var(--ui-brand-fg)", duration: "1.5s" })]}>
	{t("chat.generating")}
</Text>
```

## Used with it

The events, constants and types its module publishes, each imported from `@sdxc/ui/animations` too.

### TextShimmer.Options

Tuning for a text shimmer loop: timing, the highlight band's width and
angle of travel, its color, and the platform state it runs under.

#### Members

| Member | Type | Description |
| --- | --- | --- |
| `duration?` | `string` | Length of one sweep across the band, as a CSS time. Defaults to DEFAULT_TEXT_SHIMMER_DURATION. |
| `easing?` | `string` | CSS easing function driving the sweep. Defaults to DEFAULT_TEXT_SHIMMER_EASING. |
| `bandSize?` | `string` | Width of the moving highlight band, as a CSS length or percentage. Defaults to DEFAULT_TEXT_SHIMMER_BAND_SIZE. |
| `angle?` | `string` | CSS angle the highlight band travels along. Defaults to DEFAULT_TEXT_SHIMMER_ANGLE. |
| `color?` | `string` | Color the highlight band peaks at as it passes; the tone the text rests at between passes is this same color mixed toward transparency. Defaults to DEFAULT_TEXT_SHIMMER_COLOR. |
| `when?` | `string` | Selector fragment, relative to the host (e.g. `[data-streaming="true"]`), that gates the loop. Left unset, the loop runs as soon as it is mixed in, matching a caption mounted only while a response streams in. |