---
title: "KpiGrid"
description: "The headline figures of a report, from data: each with its change against the previous period, colored by what the change means, its definition behind an ⓘ, a line of context, a live dot and a link to what it counts. A reading of the figures sits beside one or two of them and under more."
---

> Documentation Index
> Fetch the complete documentation index at: https://epidermis.getarbol.com/llms.txt
> Use this file to discover all available pages before exploring further.

# KpiGrid

## An overview

```tsx
import { KpiGrid } from '@arbol-ai/ui';
import type { Kpi } from '@arbol-ai/ui';

const OVERVIEW: Kpi[] = [
  { id: 'live', label: 'Live now', value: 18, isLive: true, hint: '12 by phone · 6 on WhatsApp' },
  { id: 'today', label: 'Today', value: 214, change: 0.08, changeLabel: 'vs yesterday' },
  {
    id: 'rate',
    label: 'Success rate',
    value: 0.81,
    formatOptions: { style: 'percent' },
    change: 3.2,
    changeUnit: 'points',
    info: 'Conversations that reached their goal, out of every conversation with a result.',
  },
  {
    id: 'review',
    label: 'To review',
    value: 23,
    change: -0.12,
    changeTone: 'inverse',
    info: 'Conversations the agents handed to your team that nobody has closed yet.',
    link: { href: '#/kpi-grid', label: 'Review them' },
  },
];

<KpiGrid items={OVERVIEW} />
```

## One figure and its reading

A report about one figure reads it in a sentence beside it.

```tsx
import { KpiGrid } from '@arbol-ai/ui';

<KpiGrid
  items={[
    {
      id: 'duration',
      label: 'Average call',
      value: '3:45',
      unit: 'min',
      change: 0.04,
      changeTone: 'neutral',
    },
  ]}
  reading="Calls lasted a little longer than the week before; a longer call is not a worse one."
/>
```

## Loading, and a period still ahead

Placeholders hold each figure’s place; a period ahead has nothing to compare with.

```tsx
import { KpiGrid } from '@arbol-ai/ui';
import type { Kpi } from '@arbol-ai/ui';

const OVERVIEW: Kpi[] = [
  { id: 'live', label: 'Live now', value: 18, isLive: true, hint: '12 by phone · 6 on WhatsApp' },
  { id: 'today', label: 'Today', value: 214, change: 0.08, changeLabel: 'vs yesterday' },
  {
    id: 'rate',
    label: 'Success rate',
    value: 0.81,
    formatOptions: { style: 'percent' },
    change: 3.2,
    changeUnit: 'points',
    info: 'Conversations that reached their goal, out of every conversation with a result.',
  },
  {
    id: 'review',
    label: 'To review',
    value: 23,
    change: -0.12,
    changeTone: 'inverse',
    info: 'Conversations the agents handed to your team that nobody has closed yet.',
    link: { href: '#/kpi-grid', label: 'Review them' },
  },
];

<div className="grid gap-4">
  <KpiGrid isLoading items={OVERVIEW.slice(0, 3)} />
  <KpiGrid items={[{ id: 'booked', label: 'Booked for next week', value: 312, change: null }]} />
</div>
```

## Source

The examples above are [`src/blocks/kpi-grid/kpi-grid.examples.tsx`](https://github.com/getarbol/project-arbol-ui/blob/main/src/blocks/kpi-grid/kpi-grid.examples.tsx), which the library's tests render too.

Source: https://epidermis.getarbol.com/components/blocks/kpi-grid/index.mdx