---
title: "Sparkline Metric Image API — Ticker stat tiles | Imejis"
description: "Generate ticker stat tile images — a big number with a mini sparkline trendline and an auto red/green % move — with the series pushed on every API call. Try Imejis free."
url: "https://www.imejis.io/components/metric/ticker"
---

# Sparkline Metric Image API — Ticker stat tiles | Imejis

A stat tile with a mini trendline and an auto red/green delta — watchlists and live counters.

## Use cases

- Stock / crypto watchlist tiles
- Live KPI tickers for status dashboards
- Weekly trend cards posted to Slack

## Properties

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number \| string` | — | The headline value to display. |
| `label` | `string` | `""` | Caption describing the metric. |
| `labelPosition` | `'top' \| 'bottom'` | `"top"` | Whether the label sits above or below the value. |
| `format` | `'number' \| 'compact' \| 'percent' \| 'currency' \| 'none'` | `"number"` | How the value is formatted (48,250 / 48.3K / 48% / $48,250 / raw). |
| `currencySymbol` | `string` | `"$"` | Currency symbol used with the 'currency' format. |
| `prefix` | `string` | — | Text prepended to the value. |
| `suffix` | `string` | — | Text appended to the value. |
| `delta` | `number` | — | Change amount shown in the delta badge (no badge when unset). |
| `showDelta` | `boolean` | — | Show the delta badge. |
| `deltaFormat` | `'percent' \| 'value'` | `"percent"` | Whether the delta renders as a percentage or a raw value. |
| `deltaDirection` | `'up-good' \| 'down-good'` | `"up-good"` | Which direction counts as positive (colors the badge). |
| `align` | `'left' \| 'center' \| 'right'` | `"left"` | Horizontal alignment of the tile content. |
| `valueSize` | `number` (min 0) | `0` | Font size of the value in pixels. |
| `valueColor` | `color` | `"#0f172a"` | Color of the value. |
| `labelColor` | `color` | `"#64748b"` | Color of the label. |
| `deltaUpColor` | `color` | `"#16a34a"` | Badge color for a positive delta. |
| `deltaDownColor` | `color` | `"#dc2626"` | Badge color for a negative delta. |
| `sparkline` | `number[]` | `[]` | A mini trend series drawn in a strip at the bottom of the tile. When set (and delta is unset), the delta auto-derives from the first→last change. Overridable per render for watchlists. |
| `sparklineColor` | `color` | — | Line color for the sparkline; blank auto-picks red/green by direction. |
| `sparklineFill` | `boolean` | `true` | Shade the area under the sparkline. |
| `opacity` | `number` | `1` | Overall component opacity from 0 (transparent) to 1 (opaque). |
| `borderWidth` | `number` | `0` | Border thickness in pixels around the component. |
| `borderColor` | `color` | `"transparent"` | Border color (any CSS color). |
| `borderStyle` | `'solid' \| 'dashed' \| 'dotted' \| 'double' \| 'none'` | `"solid"` | Border line style. |
| `borderRadius` | `number` | `0` | Corner radius in pixels. |
| `boxShadow` | `string` | — | CSS box-shadow applied to the component, e.g. "0 4px 6px rgba(0,0,0,0.1)". |

## Design JSON (this variant)

```json
{
  "title": "Metric sample",
  "description": "A dynamic KPI tile",
  "dimensions": {
    "width": 800,
    "height": 420
  },
  "background": {
    "color": "#ffffff"
  },
  "components": [
    {
      "id": "sample-metric",
      "key": "revenue",
      "type": "metric",
      "position": {
        "x": 250,
        "y": 140
      },
      "rotation": 0,
      "size": {
        "width": 300,
        "height": 140
      },
      "dynamic": true,
      "properties": {
        "value": 48250,
        "label": "Revenue",
        "format": "compact",
        "labelPosition": "top",
        "delta": 12.5,
        "showDelta": true,
        "deltaFormat": "percent",
        "deltaDirection": "up-good",
        "align": "center",
        "opacity": 1,
        "sparkline": [
          39000,
          41000,
          43000,
          45200,
          46900,
          48200
        ]
      }
    }
  ]
}
```

## Examples

### Stock watchlist tile

A share price with an intraday sparkline; the % move colors itself green.

API overrides that reproduce this example:

```json
{
  "revenue.format": "none",
  "revenue.sparkline": [
    212,
    215,
    214,
    219,
    222,
    218,
    225,
    229.87
  ],
  "revenue.value": 229.87,
  "revenue.prefix": "$",
  "revenue.label": "AAPL"
}
```

### Churn trending down

Churn falling is good — 'down-good' colors the drop and its sparkline green.

API overrides that reproduce this example:

```json
{
  "revenue.format": "none",
  "revenue.sparkline": [
    4.1,
    4,
    3.8,
    3.9,
    3.6,
    3.4,
    3.3,
    3.2
  ],
  "revenue.value": 3.2,
  "revenue.suffix": "%",
  "revenue.label": "Churn rate",
  "revenue.deltaDirection": "down-good"
}
```

## API overrides

Push the latest number with '<key>.value' (or just '<key>') and the change with '<key>.delta'; label, format and the '<key>.sparkline' trend series are overridable too.

Flat override payload (`key.property` addressing) with the sample design's current values — send only the keys you want to change:

```json
{
  "revenue.value": 48250,
  "revenue.label": "Revenue",
  "revenue.format": "currency",
  "revenue.labelPosition": "top",
  "revenue.delta": 12.5,
  "revenue.showDelta": true,
  "revenue.deltaFormat": "percent",
  "revenue.deltaDirection": "up-good",
  "revenue.align": "center",
  "revenue.opacity": 1
}
```

```bash
curl --location 'https://render.imejis.io/v1/{{YOUR_DESIGN_ID}}' \
--header 'dma-api-key: {{YOUR_API_KEY}}' \
--header 'Content-Type: application/json' \
--data '{
    "revenue.value": 48250,
    "revenue.label": "Revenue",
    "revenue.format": "currency",
    "revenue.labelPosition": "top",
    "revenue.delta": 12.5,
    "revenue.showDelta": true,
    "revenue.deltaFormat": "percent",
    "revenue.deltaDirection": "up-good",
    "revenue.align": "center",
    "revenue.opacity": 1
}'
```

`{{YOUR_DESIGN_ID}}` and `{{YOUR_API_KEY}}` are placeholders: first create
the design in your account (paste the sample design JSON above into the
editor at https://app.imejis.io, or create it programmatically via the
imejis MCP server's `create_design` + `update_design` tools), then render
it with the design's id and one of your API keys.

Agents: the MCP server at https://api.imejis.io/api/mcp exposes this same
catalog as structured data via the `list_component_types` tool (property
kinds, allowed values, bounds, ready-to-use sample designs).

## Related

- [Metric component](https://www.imejis.io/components/metric.md) — full reference and FAQs
- [Compact](https://www.imejis.io/components/metric/compact.md) — Large numbers abbreviated (48.3K) — dashboards and social cards.
- [Negative delta](https://www.imejis.io/components/metric/negative-delta.md) — A drop against an up-is-good metric renders the badge in the down color.
- [Suffix units](https://www.imejis.io/components/metric/suffix-units.md) — Raw value with a custom suffix instead of built-in formatting.
- [Currency](https://www.imejis.io/components/metric/currency.md) — A revenue counter formatted as money with a growth delta badge.