# React Native Sankey Chart (Pro)

> A React Native Sankey chart for iOS, Android and the web: flows from sources to targets with bands as wide as what they carry, hover, press or keyboard to light a flow with a tooltip of its amount and share, theme colours, right to left, reduce motion and a screen-reader summary.

# Sankey chart

Where an amount goes: income into spending and savings, a budget into teams, visitors from their sources onto pages. Each source stacks on one side and each target on the other, joined by bands as wide as the flow they carry. Hover, press or drag over a bar or band to light it and dim the rest; on the web the chart takes keyboard focus and the arrow keys step through every bar and flow.

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

const income = [
  { key: 'Salary', value: 5500 },
  { key: 'Freelance', value: 850 },
];
const spent = [
  { key: 'Home', value: 2748 },
  { key: 'Groceries', value: 395 },
  { key: 'Eating out', value: 249 },
  { key: 'Transport', value: 241 },
  { key: 'Other', value: 337 },
  { key: 'Kept', value: 2380 },
];

export default function Example() {
  return (
    <View style={{ width: '100%', maxWidth: 640, gap: 8 }}>
      <Text weight="semibold">Cash flow this month</Text>
      <SankeyChart
        data={proportionalFlows(income, spent)}
        sourceKey="source"
        targetKey="target"
        valueKey="value"
        valueFormat="currency"
        shareLabel={(p) => `${p} of money in`}
        accessibilityLabel="Cash flow this month"
      />
    </View>
  );
}
```

## Examples

### A month's cash flow, income into spending and what was kept

Money in is pooled before it's spent, so no payment belongs to one income. `proportionalFlows` pours every source into every target in proportion, which is how budgeting apps draw it. Add a "Kept" target for what's left, or a "From savings" source when spending ran over.

```tsx live wide
import { proportionalFlows, SankeyChart } from '@patine-ui/pro';

export default function Example() {
  const flows = proportionalFlows(
    [{ key: 'Payroll', value: 4125 }, { key: 'From savings', value: 300 }],
    [{ key: 'Rent', value: 2450 }, { key: 'Groceries', value: 980 }, { key: 'Holidays', value: 995 }]
  );
  return (
    <SankeyChart
      data={flows}
      sourceKey="source"
      targetKey="target"
      valueKey="value"
      valueFormat="currency"
      shareLabel={(p) => `${p} of December`}
      style={{ width: '100%', maxWidth: 640 }}
      accessibilityLabel="December, where the money went"
    />
  );
}
```

### A marketing budget split into channels

When you know each flow, pass a row per flow. Name the nodes and pick their colours with `series`.

```tsx live wide
import { SankeyChart } from '@patine-ui/pro';

const flows = [
  { from: 'Brand', to: 'Video', amount: 42000 },
  { from: 'Brand', to: 'Social', amount: 18000 },
  { from: 'Growth', to: 'Search', amount: 36000 },
  { from: 'Growth', to: 'Social', amount: 14000 },
  { from: 'Growth', to: 'Partners', amount: 9000 },
];

export default function Example() {
  return (
    <SankeyChart
      data={flows}
      sourceKey="from"
      targetKey="to"
      valueKey="amount"
      valueFormat="compact"
      series={[{ key: 'Brand', color: '#7C3AED' }, { key: 'Growth', color: '#0284C7' }]}
      style={{ width: '100%', maxWidth: 640 }}
      accessibilityLabel="Q3 marketing budget by team and channel"
    />
  );
}
```

### Visitors from their source onto pages, coloured by source

`linkColor="source"` paints each band in its source's colour, so you can follow one source across every page it fed.

```tsx live wide
import { SankeyChart } from '@patine-ui/pro';

const visits = [
  { from: 'Search', to: 'Pricing', n: 5400 },
  { from: 'Search', to: 'Docs', n: 8100 },
  { from: 'Social', to: 'Pricing', n: 1900 },
  { from: 'Social', to: 'Blog', n: 4200 },
  { from: 'Direct', to: 'Docs', n: 3600 },
  { from: 'Direct', to: 'Pricing', n: 2100 },
];

export default function Example() {
  return (
    <SankeyChart
      data={visits}
      sourceKey="from"
      targetKey="to"
      valueKey="n"
      linkColor="source"
      shareLabel={(p) => `${p} of visits`}
      style={{ width: '100%', maxWidth: 640 }}
      accessibilityLabel="This week's visits by source and page"
    />
  );
}
```

## Guidelines

**Keep a side to five or six nodes.** Fold the small ones into "Other"; thin bands are hard to hit and their labels crowd.

**Don't show flows that don't add up.** Both sides should total the same: add "Kept" or "From savings" so the bars match.

**Name the share in the tooltip.** `shareLabel` says what the percentage is of: "of money in", "of visits".

**Don't use it for change over time.** A Sankey shows one period's flows; trends belong in a line or bar chart.

## Accessibility

| | Behaviour |
| --- | --- |
| Role | `image`, named by `accessibilityLabel` and a summary of every source and target with its amount and share. |
| Announced | The tooltip is a live region: the flow or bar under the cursor is read as it changes. |
| Keyboard (web) | Tab focuses the chart (a ring on keyboard focus only); the arrow keys, Home and End step through every bar and flow; Escape clears. |
| Touch target | Bars take touches 8 px to either side, bands across their width (at least 10 px), and tiny flows still draw a 4 px bar and a 2 px band. Press and drag to move between flows. |
| Reduce motion | The chart appears at once instead of fading in. |

## API

### SankeyChart

Also takes `style` and the theme props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` | `ChartRow[]` | **Required** | One row per flow. |
| `sourceKey` | `string` | **Required** | The row field naming where a flow starts. |
| `targetKey` | `string` | **Required** | The row field naming where it ends. |
| `valueKey` | `string` | **Required** | The row field with how much it carries. |
| `series` | `SeriesConfig[]` | — | Names and colours for nodes, matched by `key`. Default: the key, and the theme's chart palette in order. |
| `linkColor` | `'target' \| 'source'` | `'target'` | Which end's colour a band takes. |
| `shareLabel` | `(percent: string) => string` | `"45% of total"` | The tooltip's share line. |
| `nodeWidth` | `number` | `10` | The bars' width in px. |
| `nodePadding` | `number` | `8` | The gap between bars on a side, in px. |
| `height` | `number` | `280` | The drawing's height. |
| `width` | `number` | measured | A fixed width. |
| `valueFormat` | `'number' \| 'compact' \| 'currency' \| 'percent'` | `'number'` | How amounts read. `valueFormatter` wins. |
| `currency` | `string` | `'USD'` | For `valueFormat="currency"`. |
| `valueFormatter` | `(value: number) => string` | — | Your own amount format. |
| `showTooltip` | `boolean` | `true` | The readout under the cursor. |
| `renderTooltip` | `(readout: Readout) => ReactNode` | — | Your own tooltip. |
| `onPointSelect` | `(selection: ChartSelection \| null) => void` | — | Hears the cursor move to another bar or flow: the place for a haptic tick. |
| `accessibilityLabel` | `string` | — | What the chart is about, read before the summary. |
| `animate` | `boolean` | `true` | Fade in on mount. Skipped when the OS reduces motion. |
| `loading` | `boolean` | `false` | A placeholder while data loads. |
| `error` | `string` | — | Shown in place of the chart. |
| `emptyLabel` | `string` | `'No data'` | Shown when nothing flows. |
| `rtl` | `boolean` | the app's direction | Lays the chart out right to left: sources on the right. |
| `style` | `StyleProp<ViewStyle>` | — | The outer view. |
| `theme` / `design` | | | |

#### proportionalFlows

`proportionalFlows(sources, targets)` turns two lists of totals (`{ key, value }`) into rows where every source pours into every target in proportion: for money pooled before it's spent. `collectFlows` adds up rows with the same ends, and `sankeyLayout(flows, width, height, nodeWidth, gap)` returns the bars and bands for a drawing of your own.
