# Sparkline

> A tiny trend line, inline with text or in a table cell. Plain SVG, with no Recharts.

- Name: `sparkline`
- Status: beta
- Categories: charts
- File: the install writes `sparkline.tsx` to your `ui` alias, `@/components/ui` by default.
- Other registry items: `@arbokui/chart`, `@arbokui/skeleton`, `@arbokui/dither`. The install adds them.
- Gallery: https://arbokui.com/components/sparkline
- Registry item: https://arbokui.com/r/sparkline.json

## Install

1. Add the registry to `components.json`. Do this first, once:

   ```bash
   npx shadcn@latest registry add "@arbokui=https://arbokui.com/r/{name}.json"
   ```

   The command writes this entry. You can also add it by hand:

   ```json
   {
     "registries": {
       "@arbokui": "https://arbokui.com/r/{name}.json"
     }
   }
   ```

   Without this step, the shadcn CLI looks up `@arbokui` in a public list that Arbokui does not control.

2. Add the theme once per app. It replaces your color tokens with ones checked for contrast:

   ```bash
   npx shadcn@latest add @arbokui/theme
   ```

3. Add the component:

   ```bash
   npx shadcn@latest add @arbokui/sparkline
   ```

## Use it for

- Showing the shape of a trend next to a number, in a stat card, or in a table row.
- Name it with aria-label, like "Revenue, last 30 days". Screen readers hear the name with the first and last values.
- Use tone for meaning: success for a good trend, danger for a bad one, neutral when it is neither.
- Pass the numbers oldest first.

## Avoid it for

- When people need to read exact values or dates. Use LineChart, which has axes and a tooltip.
- Comparing two or more series. Use LineChart.
- As the only place a number appears. Show the current value in text next to it.

## Props

- `data`: `number[]`. The numbers to draw, oldest first. Values that are not finite numbers are skipped.
- `aria-label`: `string`. Required. Names the trend. Screen readers hear it with the first and last values.
- `tone`: `"neutral" | "brand" | "danger" | "success" | "warning"`. Default `"neutral"`. The line's color role.
- `size`: `"sm" | "md" | "lg"`. Default `"md"`. Height and width, from --control-h-sm, so density scales it. Small fits a line of text.
- `area`: `boolean`. Default `false`. Fills the space under the line with the tone at 15%.
- `loading`: `boolean`. Default `false`. Shows a skeleton at the same size.
- `valueFormat`: `Intl.NumberFormatOptions`. Formats the first and last values that screen readers hear.
- `locale`: `string`. Default `"en-US"`. The locale for those numbers.
- `texture`: `"flat" | "dither" | "gradient" | "grain"`. dither draws the area as dots, gradient fades it from the top, and grain speckles it. The line glows on dark pages. Hover fills gradient and grain in. Left out, the line follows the Texture around it.
- `className`: `string`. Extra classes. Later classes win, so className='w-full' stretches it.

## Accessibility

- Renders a \<span role="img">. Its name is your aria-label plus the first and last values, like "Revenue: 12.4 to 23.9". TypeScript requires aria-label.
- The words it adds, "to", "loading", and "no data", are English.
- The SVG inside is hidden from screen readers, so they hear the name once.
- The line takes the tone's solid color, which the theme tests hold to 3:1 against the page and cards, in light and dark.
- It has no tab stop, because it has nothing to interact with. Put exact values in text nearby.
- It draws on the server and never animates, so its space and shape are in the static HTML.

## Examples

### Next to a number

```tsx
<p className="flex items-center gap-2">
  $23.9K
  <Sparkline data={[12.4, 14.1, 13.2, 16.8, 18.7, 23.9]} tone="success" aria-label="Revenue, last 6 weeks" />
</p>
```

### In a table cell, filled

```tsx
<td>
  <Sparkline data={row.history} area tone="brand" aria-label={`${row.name}, last 30 days`} />
</td>
```

### While it loads

```tsx
<Sparkline data={data ?? []} loading={isLoading} aria-label="Revenue, last 6 weeks" />
```

### A grain area that fills in on hover

```tsx
<Sparkline area tone="success" data={[4, 6, 5, 8, 7, 9]} texture="grain" aria-label="Revenue, last 6 weeks" />
```