# React Native Stat (KPI tile)

> A React Native Stat / KPI component for dashboards on iOS, Android and the web: a label, a big figure, a green or red change with an arrow, a description, read as one sentence by screen readers.

# Stat

A key figure with its label and how it moved: the tiles at the top of a dashboard. The change is green when it's good and red when it's bad, with an arrow so color isn't the only cue.

```tsx
import { Stat } from 'patine-ui';
```

```tsx live
import { Card, Grid, Stat } from 'patine-ui';
import { Icon } from '@patine-ui/icons';

const KPIS = [
  { label: 'Revenue', value: '$48,210', change: '+12.5%', icon: 'banknote' },
  { label: 'Active users', value: '2,381', change: '+4.1%', icon: 'users' },
  { label: 'Churn', value: '2.1%', change: '-0.4%', invertTrend: true, icon: 'trendingDown' },
  { label: 'Avg. response', value: '1.8 s', change: '+0.3 s', invertTrend: true, icon: 'timer' },
] as const;

export default function Example() {
  return (
    <Grid minColumnWidth={180} gap="md" style={{ maxWidth: 640 }}>
      {KPIS.map(({ icon, ...kpi }) => (
        <Card key={kpi.label} style={{ padding: 16 }}>
          <Stat {...kpi} description="vs last month" icon={<Icon name={icon} />} />
        </Card>
      ))}
    </Grid>
  );
}
```

## Example: today in a shop

A shop's home screen: four numbers for the chosen period, each with its change against the period before. For refunds a rise is bad, so `invertTrend` colors it red.

```tsx live
import { useState } from 'react';
import { Card, Grid, SegmentedControl, Stat, VStack } from 'patine-ui';
import { Icon } from '@patine-ui/icons';

const DATA = {
  today: [
    { label: 'Orders', value: '64', change: '+9', icon: 'package' },
    { label: 'Revenue', value: '€3,912', change: '+14%', icon: 'banknote' },
    { label: 'Conversion', value: '3.4%', change: '+0.2 pt', icon: 'percent' },
    { label: 'Refunds', value: '2', change: '+1', invertTrend: true, icon: 'refreshCcw' },
  ],
  week: [
    { label: 'Orders', value: '402', change: '-3%', icon: 'package' },
    { label: 'Revenue', value: '€24,180', change: '-1%', icon: 'banknote' },
    { label: 'Conversion', value: '3.1%', change: '-0.3 pt', icon: 'percent' },
    { label: 'Refunds', value: '9', change: '-4', invertTrend: true, icon: 'refreshCcw' },
  ],
} as const;

export default function Example() {
  const [range, setRange] = useState<keyof typeof DATA>('today');
  return (
    <VStack gap="md" style={{ width: '100%', maxWidth: 640 }}>
      <SegmentedControl items={[{ label: 'Today', value: 'today' }, { label: 'Last 7 days', value: 'week' }]} value={range} onValueChange={setRange} style={{ alignSelf: 'flex-start' }} />
      <Grid minColumnWidth={150} gap="md">
        {DATA[range].map(({ icon, ...kpi }) => (
          <Card key={kpi.label} style={{ padding: 16 }}>
            <Stat {...kpi} description={range === 'today' ? 'vs yesterday' : 'vs the week before'} icon={<Icon name={icon} />} />
          </Card>
        ))}
      </Grid>
    </VStack>
  );
}
```

## Trend

The trend comes from `change`: a leading `-` or `−` (or a negative number) is down, zero is neutral, anything else is up. Set `trend` to say it yourself. For figures where down is good, such as costs, churn or load time, set `invertTrend`.

## With a chart

Children go below the figure, such as a [Sparkline](./sparkline).

## Designs

brand and web draw a bold figure with colored change text, as shadcn's dashboard cards. iOS and Material put the change in a tinted pill.

## Accessibility

The tile is one element, read as a sentence: "Revenue, $48,210, up 12.5%, vs last month". The arrow and the word "up" or "down" carry the trend without color.

## Props

Also takes `View` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | — | What's measured. |
| `value` | `ReactNode` | — | The figure, formatted. |
| `change` | `string \| number` | — | How it moved: `'+12.5%'`, or a number. |
| `trend` | `'up' \| 'down' \| 'neutral'` | from `change` | Sets the arrow and color. |
| `invertTrend` | `boolean` | `false` | Down is good: green for down, red for up. |
| `description` | `ReactNode` | — | Under the value, e.g. `'vs last month'`. |
| `icon` | `ReactNode` | — | Beside the label. |
| `children` | `ReactNode` | — | Below, such as a chart. |
| `styles` | `{ label?, value?, change?, description? }` | — | Slot styles. |
| `theme`, `design` | | | As every component. |
