# React Native Stats Row, KPI tiles (Pro)

> A React Native stats row for iOS, Android and the web: dashboard KPI tiles with the change in words, arrows and color, sparkline trends, currency and percent formats, wrapping or scrolling, and selectable tiles that switch a chart. Accessible and themeable.

# Stats row Pro

A dashboard's key figures in a row. Each tile shows its value, how it changed (green when it's good news, red when it isn't, with an arrow so color isn't the only cue) and an optional trend. The row wraps to fit, or scrolls sideways on phones. Tiles can be buttons, or tabs that pick which figure a chart shows. Each tile is read as one sentence: "Revenue, $48,250, up 18% vs last period".

```tsx
import { StatsRow } from '@patine-ui/pro';
```

```tsx live full
import { StatsRow } from '@patine-ui/pro';

const stats = [
  { key: 'revenue', label: 'Revenue', value: 4825000, previous: 4100000, valueFormat: 'currency', trend: [31, 34, 33, 38, 41, 39, 46, 48] },
  { key: 'customers', label: 'New customers', value: 1284, previous: 1190, trend: [10, 12, 11, 14, 13, 15, 17, 16] },
  { key: 'churn', label: 'Churn', value: 0.021, delta: -0.12, good: 'down', valueFormat: 'percent' },
  { key: 'uptime', label: 'Uptime', value: '99.98%', description: 'Last 30 days' },
];

export default function Example() {
  return <StatsRow items={stats} style={{ width: '100%' }} />;
}
```

## Example: a newsletter's dashboard

A newsletter's last issue: subscribers, opens, clicks and unsubscribes against the issue before, each read the right way round, so fewer unsubscribes shows as good news. Press a tile to see what it counts.

```tsx live wide
import { useState } from 'react';
import { View } from 'react-native';
import { Text } from 'patine-ui';
import { StatsRow } from '@patine-ui/pro';

const STATS = [
  { key: 'subs', label: 'Subscribers', value: 18240, previous: 17610, trend: [15.2, 15.9, 16.4, 17.1, 17.6, 18.2], description: 'Everyone on the list today' },
  { key: 'opens', label: 'Open rate', value: 0.482, previous: 0.455, valueFormat: 'percent', description: 'Opened at least once' },
  { key: 'clicks', label: 'Click rate', value: 0.061, previous: 0.072, valueFormat: 'percent', description: 'Clicked any link' },
  { key: 'unsubs', label: 'Unsubscribes', value: 38, previous: 61, good: 'down', description: 'Left after this issue' },
];

export default function Example() {
  const [picked, setPicked] = useState<string | null>(null);
  return (
    <View style={{ width: '100%', gap: 8 }}>
      <StatsRow items={STATS} period="vs issue #141" onItemPress={(item) => setPicked(item.key)} value={picked ?? undefined} />
      <Text size="sm" color="textSecondary">{picked ? STATS.find((s) => s.key === picked)?.description : 'Issue #142 · sent Tuesday 07:00'}</Text>
    </View>
  );
}
```

## Values and changes

A number `value` is formatted with `valueFormat` (`'number'`, `'compact'`, `'currency'` or `'percent'` for fractions), per tile or for the row; a string is shown as it is. Give `previous` and the change is worked out, or `delta` as a ratio (`0.12` is +12%). Set `good: 'down'` for figures where falling is good news, like churn or costs. `valueFormatter` formats every number your way.

## Tiles that switch a chart

Give `value` and `onValueChange` (or `defaultValue`) and the tiles become tabs, as Stripe's dashboard does: the chosen one is marked and the chart under it follows.

```tsx live full
import { StatsRow, LineChart } from '@patine-ui/pro';

const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'];
const data = months.map((month, i) => ({ month, revenue: [31, 34, 38, 41, 46, 48][i] * 1000, orders: [210, 240, 236, 290, 320, 344][i] }));
const stats = [
  { key: 'revenue', label: 'Revenue', value: 48000, previous: 46000, valueFormat: 'currency' },
  { key: 'orders', label: 'Orders', value: 344, previous: 320 },
];

export default function Example() {
  const [metric, setMetric] = React.useState('revenue');
  return (
    <View style={{ width: 520, gap: 16 }}>
      <StatsRow items={stats} value={metric} onValueChange={setMetric} />
      <LineChart data={data} xKey="month" series={[{ key: metric, label: metric === 'revenue' ? 'Revenue' : 'Orders' }]} valueFormat={metric === 'revenue' ? 'currency' : 'number'} height={180} />
    </View>
  );
}
```

## Variants and sizes

`variant` is `'cards'`, `'plain'`, `'divided'` (one bordered strip split by hairlines, as Tremor draws it) or `'tinted'`; the default follows the design. `size` is `'sm'`, `'md'` or `'lg'`.

```tsx live full
import { StatsRow } from '@patine-ui/pro';

const stats = [
  { key: 'mrr', label: 'MRR', value: 128400, previous: 119000, valueFormat: 'currency' },
  { key: 'arpu', label: 'ARPU', value: 42.5, previous: 44.1, valueFormat: 'currency' },
  { key: 'nps', label: 'NPS', value: 61, delta: 0.05 },
];

export default function Example() {
  return (
    <View style={{ width: 560, gap: 24 }}>
      <StatsRow items={stats} variant="divided" />
      <StatsRow items={stats} variant="plain" size="lg" />
      <StatsRow items={stats} variant="tinted" size="sm" density="compact" />
    </View>
  );
}
```

## Live figures

Tiles rise in once when they mount; after that, new values update in place without moving the layout.

```tsx live full
import { StatsRow } from '@patine-ui/pro';

export default function Example() {
  const [visitors, setVisitors] = React.useState(1820);
  React.useEffect(() => {
    const id = setInterval(() => setVisitors((v) => v + Math.round(Math.random() * 12 - 3)), 1500);
    return () => clearInterval(id);
  }, []);
  return (
    <StatsRow
      style={{ width: 420 }}
      items={[
        { key: 'live', label: 'Visitors right now', value: visitors, previous: 1800, icon: 'users' },
        { key: 'conv', label: 'Conversion', value: 0.034, delta: 0.08, valueFormat: 'percent', icon: 'target' },
      ]}
    />
  );
}
```

## States

`loading` shows a skeleton of the tiles (`skeletonCount` of them), `error` an error with `onRetry`, and an empty `items` its empty state.

```tsx live full
import { StatsRow } from '@patine-ui/pro';

export default function Example() {
  return (
    <View style={{ width: 560, gap: 24 }}>
      <StatsRow items={[]} loading skeletonCount={3} />
      <StatsRow items={[]} error="We couldn't load your figures" onRetry={() => {}} />
    </View>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `StatItem[]` | — | `{ key, label, value, previous?, delta?, good?, period?, icon?, trend?, description?, valueFormat?, disabled? }` |
| `variant` | `'cards'` \| `'plain'` \| `'divided'` \| `'tinted'` | the design's | |
| `size` | `'sm'` \| `'md'` \| `'lg'` | `'md'` | The figures' size. |
| `columns` | `number` | as many as fit | Tiles per row. |
| `minTileWidth` | `number` | `160` | The narrowest a tile gets before the row wraps. |
| `scrollable` | `boolean` | `false` | One row that scrolls sideways. |
| `valueFormat` | `'number'` \| `'compact'` \| `'currency'` \| `'percent'` | `'number'` | |
| `currency` / `locale` | `string` | `'USD'` / device | |
| `valueFormatter` | `(value, item) => string` | — | |
| `period` | `string` | `'vs last period'` | What changes compare against. |
| `showTrend` / `trendVariant` | `boolean` / `'line'` \| `'area'` \| `'bar'` | `true` / `'area'` | |
| `value` / `defaultValue` / `onValueChange` | `string` | — | Selectable tiles (tabs). |
| `onItemPress` | `(item) => void` | — | Tiles as buttons. |
| `renderItem` | `(info) => ReactNode` | — | Draw a tile's content yourself. |
| `loading` / `error` / `onRetry` / `emptyTitle` / `emptyDescription` / `renderEmpty` / `skeletonCount` | | | States. |
| `density` / `animate` / `labels` / `design` / `theme` / `accessibilityLabel` / `style` | | | |
