# ASCII Chart

> Sparklines and labelled bar charts drawn with block elements.

Category: Charts. Docs: https://asciicn.sumak.dev/docs/ascii-chart

## Installation

```bash
npx shadcn@latest add @asciicn/ascii-chart
```

Needs the `@asciicn` registry in components.json: `"registries": { "@asciicn": "https://asciicn.sumak.dev/r/{name}.json" }`.

## Usage

```tsx
import { AsciiBarChart, AsciiSparkline } from "@/components/ascii/ascii-chart"

<AsciiSparkline data={[3, 5, 4, 8, 12]} label="Signups, last 5 days" />

<AsciiBarChart
  data={[{ label: "cpu", value: 62 }, { label: "mem", value: 31 }]}
  format={(v) => `${v}%`}
/>
```

## Examples

### Sparklines in a table

One character per value means a sparkline fits in a table cell and lines up across rows. Pass the same `min` and `max` to compare rows fairly.

```tsx
{services.map((s) => (
  <tr key={s.name}>
    <td>{s.name}</td>
    <td>
      <AsciiSparkline data={s.latency} min={0} max={400} label={`${s.name} latency`} />
    </td>
  </tr>
))}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` | `number[] | { label, value }[]` |  | Sparkline takes numbers, bar chart takes labelled rows. |
| `label` | `string` |  | Sparkline only. Describe the trend for screen readers. |
| `min / max` | `number` | `data range` | Fix the scale. |
| `width` | `number` | `32` | Bar chart: characters for the largest bar. |
| `format` | `(v) => string` | `String` | Bar chart value label. |
| `animate` | `boolean` | `true` | Sparklines rise in from the left and bars grow row by row the first time they scroll into view. |

## Notes

- **Accessibility.** Sparklines are `role="img"` with your `label`. Bar charts are a `role="table"` with row headers, so values are read as data.
- **Precision.** Eighth blocks (▁ to █ and ▏ to █) give eight steps inside each character.
- **Dependencies.** None. Plain text, safe in Server Components and emails.