@rific/heatmap

GitHub-style activity heatmap for React Native. SVG cells with multiple visualization modes, touch tooltips, animations, and a flexible color scale API.

Installation

npm install @rific/heatmap

Peer dependencies

npm install react-native-svg

Follow the react-native-svg installation guide to link the native module.

Usage

import Heatmap from '@rific/heatmap'

const data = [
  { date: '2026-01-15', value: 3 },
  { date: '2026-03-08', value: 14 },
  { date: '2026-05-01', value: 7 },
]

export default function App() {
  return (
    <Heatmap.Calendar
      data={data}
      onDayPress={(point, date) => console.log(date, point)}
    />
  )
}

Props

Prop	Type	Default	Description
data	DataPoint[]	required	Array of { date, value } objects. date is YYYY-MM-DD.
startDate	Date	1 year ago	First day shown on the grid.
endDate	Date	Today	Last day shown on the grid.
cellMode	'solid' | 'gradient' | 'density' | 'stacked' | 'dots' | 'priority'	'solid'	Visual style of each cell.
colorScale	Partial<ColorScale>	GitHub greens	Thresholds and colors used to shade cells.
color	string	—	Single accent color. Overrides the default color scale.
colorScheme	'light' | 'dark'	—	Switch between built-in light and dark palettes.
autoScale	boolean	true	Scale cell intensity relative to the max value in data.
theme	Partial<HeatmapTheme>	See below	Size, spacing, and color overrides.
showMonthLabels	boolean	true	Show month name labels above the grid.
showDayLabels	boolean	true	Show Mon / Wed / Fri labels on the left.
animated	boolean	false	Enable all animations (load ripple, today pulse, press spring).
scrollToToday	boolean	true	Scroll to the current week on mount.
scrollEnabled	boolean	true	Enable or disable horizontal scrolling.
onDayPress	(point: DataPoint | null, date: string) => void	—	Called when a cell is tapped.
onEndReached	() => void	—	Called when the user scrolls near the right edge. Use for infinite scroll.
onEndReachedThreshold	number	0.1	Fraction of total width from the right edge that triggers onEndReached.
renderTooltip	(data: TooltipData) => ReactNode	—	Replace the default tooltip with a custom component.
renderCell	(data: DataPoint | null, date: string) => ReactNode	—	Replace the default cell with a custom component.
tooltipLabel	string	'event'	Unit label in the default tooltip. Pluralized automatically (e.g. 'workout' → '3 workouts').
tooltipEmptyLabel	string	'No events'	Label shown in the tooltip for days with no data.

Cell modes

solid (default)

Each cell is a flat colored rectangle, identical to the GitHub contribution graph.

gradient

A radial gradient blooms from the center of each cell — dim at the center, full color at the edges.

density

A circle grows inside a neutral background rectangle. A small dot means low activity; a filled square means high activity.

stacked

Horizontal slices represent proportional segments from the segments array on each DataPoint.

dots

Each segment in the segments array is drawn as a dot sized by its relative weight.

priority

The dominant segment's color fills the cell at an opacity proportional to its value.

<Heatmap.Calendar data={data} cellMode='density' />

Animations

Pass animated to enable all animations. No extra dependencies — uses the built-in Animated API.

<Heatmap.Calendar data={data} animated />

• Load ripple — cells fade and scale in on mount, radiating outward from today's column.
• Today pulse — the current day cell breathes with a looping scale animation.
• Press spring — cells scale down on press and spring back on release.

The current day always receives a border indicator regardless of the animated prop.

Infinite scroll

<Heatmap.Calendar
  data={data}
  startDate={startDate}
  endDate={endDate}
  onEndReached={() => setEndDate(extendedDate)}
  onEndReachedThreshold={0.15}
/>

When the user scrolls within onEndReachedThreshold of the right edge, onEndReached fires. Update endDate to append more weeks.

Segments

For multi-category data, pass a segments array on each DataPoint. Works with stacked, dots, and priority cell modes.

const data = [
  {
    date: '2026-05-01',
    value: 10,
    segments: [
      { color: '#40c463', value: 6 },
      { color: '#216e39', value: 4 },
    ],
  },
]

<Heatmap.Calendar data={data} cellMode='stacked' />

Color scale

<Heatmap.Calendar
  data={data}
  colorScale={{
    thresholds: [1, 4, 8, 16],   // 4 thresholds → 5 colors
    colors: ['#ebedf0', '#9be9a8', '#40c463', '#30a14e', '#216e39'],
    emptyColor: '#ebedf0',
  }}
/>

Values below the first threshold use colors[0]. Values at or above threshold n use colors[n + 1]. Values above the last threshold use the last color.

Theme

<Heatmap.Calendar
  data={data}
  theme={{
    cellSize: 14,
    cellRadius: 2,
    gutterSize: 2,
    monthLabelColor: '#57606a',
    dayLabelColor: '#57606a',
    backgroundColor: 'transparent',
    tooltipBackgroundColor: '#1b1f23',
    tooltipTextColor: '#ffffff',
    todayColor: '#4183c4',
    todayBorderColor: '#4183c4',
  }}
/>

Custom tooltip

<Heatmap.Calendar
  data={data}
  renderTooltip={({ date, value }) => (
    <View style={styles.tooltip}>
      <Text>{date} — {value} events</Text>
    </View>
  )}
/>

Custom cell

<Heatmap.Calendar
  data={data}
  renderCell={(point, date) => (
    <View style={{ width: 14, height: 14, backgroundColor: point ? 'tomato' : '#eee', borderRadius: 2 }} />
  )}
/>

TypeScript

All types are exported:

import Heatmap, { type CellMode, type ColorScale, type DataPoint, type HeatmapProps, type HeatmapTheme, type TooltipData } from '@rific/heatmap'

Development

npm run typecheck   # TypeScript
npm run lint        # ESLint
npm run fix         # ESLint --fix
npm test            # Jest
npm run test:watch  # Jest watch mode

License

MIT © Jay Deaton