# React Native Charts (Pro)

> Accessible, animated React Native charts for iOS, Android and the web: line, area, bar, combo, pie, donut, radial, gauge, calendar heatmap, scatter, bubble, funnel, Sankey, radar, sparkline and status tracker. Live data that glides, stacked and 100% layouts, reference lines, goals, legend toggles, scrubbing with haptic-ready callbacks, loading and empty states, RTL, dark mode and screen-reader summaries. Built on react-native-svg.

# Charts Pro

Fifteen charts for phones and the web, from one codebase. They take rows of data the way recharts and shadcn's charts do (`{ month: 'Jan', revenue: 120 }`), so moving data in is a rename, and they move: they grow in on mount and glide to new values when your data changes, so a live feed looks alive instead of flickering.

```tsx
import {
  AreaChart, BarChart, ComboChart, DonutChart, FunnelChart, GaugeChart, HeatmapChart, LineChart,
  PieChart, RadarChart, RadialChart, SankeyChart, ScatterChart, Sparkline, StatusTracker,
} from '@patine-ui/pro';
```

Charts are part of Patine Pro and draw with `react-native-svg`, an optional peer that runs in Expo Go and on the web: `npx expo install react-native-svg`. Everything else in Patine needs no peer at all.

| Chart | Use it for | Page |
| --- | --- | --- |
| `LineChart`, `AreaChart` | Trends over time; stacked and 100% areas, forecasts | [Line & Area](./line-chart) |
| `BarChart` | Comparing categories; grouped, stacked, 100%, horizontal, with goals | [Bar](./bar-chart) |
| `ComboChart` | Bars and lines together, with a second axis | [Combo](./combo-chart) |
| `PieChart`, `DonutChart` | Parts of a whole; half donuts | [Pie & Donut](./pie-chart) |
| `RadialChart` | Progress toward goals, as activity rings | [Radial](./radial-chart) |
| `GaugeChart` | One value against its range | [Gauge](./gauge-chart) |
| `HeatmapChart` | Activity per day, as a contribution calendar | [Heatmap](./heatmap-chart) |
| `ScatterChart` | How two measures relate; bubbles, trend line | [Scatter & Bubble](./scatter-chart) |
| `FunnelChart` | Conversion through stages | [Funnel](./funnel-chart) |
| `SankeyChart` | Where an amount goes: income into spending, traffic into pages | [Sankey](./sankey-chart) |
| `RadarChart` | Several measures of a few things | [Radar](./radar-chart) |
| `Sparkline` | A small trend beside a number | [Sparkline](./sparkline) |
| `StatusTracker` | Uptime or health per period | [Status tracker](./status-tracker) |

## What every chart does

- **Moves with your data**: bars grow, lines glide, slices turn and rings fill to new values; nothing animates when the OS asks to reduce motion, or with `animate={false}`.
- **Reads under the finger**: drag across a chart on a phone to scrub it, hover on the web, or focus it and use the arrow keys, Home, End and Escape. `onPointSelect` hears every move (and `null` when the cursor leaves): call your haptics there, or show the value in a header. `renderTooltip` draws your own tooltip.
- **Legend toggles**: press a legend item to turn its series off and on; the last one showing stays on. `defaultHidden` starts some off.
- **Formats values**: `valueFormat="currency"` (with `currency`), `"percent"` (values are fractions), `"compact"` or `"number"`; axes get the short form (`$1.2K`), tooltips the full one (`$1,234.50`). `valueFormatter` takes over entirely.
- **Has states**: `loading` shows a pulsing placeholder, `error` a message, and no data `emptyLabel`.
- **Readable without color**: each series has its own marker shape in the legend and tooltip, and the palette (the theme's primary, then its colour-blind-safe `theme.chart` series colours) is nudged to 3:1 contrast against the background, light or dark.
- **Read aloud**: a chart is one image to a screen reader, named by your `accessibilityLabel` and a summary generated from the data: the range, the highest and lowest values and the trend (or shares, conversion, correlation).
- **Right to left**: in an RTL app (or with `rtl`) time runs leftward and the value axis swaps sides.
- **Follows the design**: Swift Charts' hairline grid and trailing value axis on iOS, Material 3's baseline and fully rounded bars, the web's dashed grid, and Patine's brand look; light and dark.
- **Fits its container**: it measures its width on layout; pass `width` to fix it, and `height` for the drawing.

## Shared props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` | `object[]` | — | One row per x value (or slice, ring, stage, day). |
| `height` | `number` | `240` | The drawing's height; the legend sits outside it. |
| `width` | `number` | fills the container | |
| `showLegend` | `boolean` | more than one series | |
| `legendPosition` | `'top' \| 'bottom'` | `'bottom'` | |
| `showTooltip` | `boolean` | `true` | Also turns off scrubbing and keyboard focus. |
| `renderTooltip` | `(readout) => ReactNode` | — | Your own tooltip from `{ title, items, x, y }`. |
| `onPointSelect` | `(selection \| null) => void` | — | `{ index, row, label }` on each move of the cursor. |
| `valueFormat` | `'number' \| 'compact' \| 'currency' \| 'percent'` | `'number'` | |
| `currency` | `string` | `'USD'` | For `valueFormat="currency"`. |
| `valueFormatter` | `(value: number) => string` | — | Wins over `valueFormat`, on axes too. |
| `loading` | `boolean` | `false` | A pulsing placeholder. |
| `error` | `string` | — | Shown in place of the drawing. |
| `emptyLabel` | `string` | `'No data'` | Shown when there's nothing to draw. |
| `rtl` | `boolean` | the app's direction | |
| `accessibilityLabel` | `string` | — | The chart's title for screen readers. |
| `animate` | `boolean` | `true` | Grow in and glide to new data. |
| `style` | `StyleProp<ViewStyle>` | — | |
| `theme` / `design` | | provider's | |

## Cartesian props

Line, area, bar and combo charts also take:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `xKey` | `string` | — | The row field on the x axis: categories, numbers or `Date`s (a time axis). |
| `series` | `{ key, label?, color?, dashed?, dashFrom? }[]` | — | Colors come from the theme's validated palette unless you set them. |
| `grid` | `'value' \| 'category' \| 'both' \| 'none'` | `'value'` | Which gridlines; `showGrid={false}` is `'none'`. |
| `showXAxis` / `showYAxis` | `boolean` | `true` | |
| `minValue` / `maxValue` | `number` | from the data | Pin the value axis's ends. |
| `tickCount` | `number` | one per 44px | About this many value ticks. |
| `referenceLines` | `{ value, label?, color?, dashed? }[]` | — | Lines at values: a target, an average, a limit. |
| `referenceBands` | `{ from, to, label?, color? }[]` | — | Shaded ranges: a target zone, normal limits. |
| `defaultHidden` | `string[]` | — | Series keys turned off at first. |
| `xFormatter` | `(x) => string` | — | Formats x values on the axis and in the tooltip. |

## Haptics on scrub

Patine has no native code, so it leaves the buzz to you: `onPointSelect` fires once per point as the finger crosses it.

```tsx
import * as Haptics from 'expo-haptics';

<LineChart {...props} onPointSelect={(point) => point && Haptics.selectionAsync()} />;
```
