# <motion-sparkline>

A small trend line that sits inside a sentence, a table cell or a stat
tile. It draws itself in when it scrolls into view, and springs to new
values when `values` or `data` changes.

**Use it for:** a small trend next to a number, in a sentence, a table cell
or a stat tile, where the shape matters more than the exact values.

**Avoid it for:** data people need to read exactly or explore. It has no
axes, tooltip or keyboard support; use `motion-chart` instead.

**Accessibility:** it has `role="img"` and an `aria-label`: your `label`,
or a generated summary such as "from 3 to 11, low 3, high 11". The drawing
itself is hidden, and the sparkline is not focusable. The summary has no
units or context, so set `label`, for example "Signups this week, from 3
to 11", when the text nearby does not explain the trend.

**Reduced motion:** the line appears in full at once when the draw-in would
start (on mount, or when half of it is in view). New values replace the old
ones at once.

**Common mistakes:** passing fewer than two values: nothing is drawn.
Writing thousands separators, such as `1,200`: commas separate values, so
it reads as 1 and 200.

Docs: https://www.motion-components.dev/docs/charts/motion-sparkline/

## Install

```js
import 'motion-components/motion-sparkline'
```

Or without a build step:

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/motion-components@1/dist/motion-sparkline.js/+esm"></script>
```

## Example

```html
Signups this week <motion-sparkline values="3, 5, 4, 8, 7, 11"></motion-sparkline>
```

## Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `values` | `string` | `''` | Comma-separated numbers. Ignored when `data` is set. |
| `area` | `boolean` | `false` | Fills the area under the line with a light wash. |
| `trigger` | `'view' \| 'mount'` | `'view'` | When the draw-in runs: `'view'` (scrolled into view) or `'mount'`. |
| `duration` | `number` | `1` | Spring duration in seconds. |
| `bounce` | `number` | `0.2` | Spring bounciness when the values change. |
| `label` | `string` | `''` | Accessible name. Without it the name describes the trend, for example "from 3 to 11, low 3, high 11". |

## Properties

| Property | Type | Description |
| --- | --- | --- |
| `data` | `number[] \| null` | The numbers as an array, set from JavaScript. Takes precedence over `values`. |
| `playState` | `'idle' \| 'running' \| 'paused' \| 'finished'` | Current state: `'idle'`, `'running'`, `'paused'` or `'finished'`. |
| `finished` | `Promise<void>` | Resolves when the current run settles. A new run replaces the promise. |

## Methods

| Method | Description |
| --- | --- |
| `replay()` | Draws the line in again. |
| `play()` | Starts the animation, or resumes it when paused. Resolves once the run settles. Under `prefers-reduced-motion: reduce` the final state is applied immediately without animating. |
| `pause()` | Holds the animation at its current position. No-op unless running. |
| `finish()` | Jumps to the final state and settles. Fires `motion-finish`. |
| `cancel()` | Reverts to the initial state and returns to idle. Fires `motion-cancel`. |

## Events

The `motion-*` events bubble and are composed.

| Event | Description |
| --- | --- |
| `motion-start` | When the draw-in starts. |
| `motion-finish` | When the draw-in finishes. |
| `motion-cancel` | When `cancel()` stops a run and resets it. |

## CSS custom properties

| Property | Description |
| --- | --- |
| `--mc-sparkline-width` | Width. Default `6em`. |
| `--mc-sparkline-height` | Height. Default `1.5em`. |
| `--mc-sparkline-color` | Line color. Default `currentColor`. |
| `--mc-sparkline-accent` | Color of the dot on the last value. Default the line color. |