@symbiot.dev/react-native-heatmap/README.md

A lightweight and customizable activity graph for React Native, perfect for visualizing user engagement, habits, streaks, or productivity over time.

<div align="center">
  <h1>React Native Heatmap 🔥📊</h1>
</div>

> **react-native-heatmap** is a lightweight and customizable activity graph for React Native. Perfect for visualizing user engagement, habits, streaks, or productivity over time.
> It supports **iOS**, **Android**, **Web**, and **Expo**, making it easy to drop into any cross-platform app.

<div align="center">
  <img alt="NPM downloads" src="https://img.shields.io/npm/dw/@symbiot.dev/react-native-heatmap?logo=npm&label=npm&cacheSeconds=3600"/>
  <img alt="NPM version" src="https://img.shields.io/npm/v/@symbiot.dev/react-native-heatmap?logo=npm&label=npm&cacheSeconds=3600"/>
  <img alt="Bundle size" src="https://img.shields.io/bundlephobia/minzip/@symbiot.dev/react-native-heatmap?label=size&cacheSeconds=3600"/>
  <img alt="Typescript" src="https://img.shields.io/static/v1?label=&message=TS&color=blue"/>
</div>

---

## [📱 Demo](#demo)

<div>
  <h3 align="center">WeeklyHeatMap</h3>
  <div align="center">
    <img alt="Demo 1" src="https://github.com/symbiotdev/react-native-heatmap/blob/main/assets/1.png" width="200px" height="400px" />
    <img alt="Demo 2" src="https://github.com/symbiotdev/react-native-heatmap/blob/main/assets/2.png" width="200px" height="400px" />
    <img alt="Demo 3" src="https://github.com/symbiotdev/react-native-heatmap/blob/main/assets/3.png" width="200px" height="400px" />
    <img alt="Demo 4" src="https://github.com/symbiotdev/react-native-heatmap/blob/main/assets/4.png" width="200px" height="400px" />
  </div>
  <h3 align="center">MonthlyHeatMap</h3>
  <div align="center">
    <img alt="Demo 5" src="https://github.com/symbiotdev/react-native-heatmap/blob/main/assets/5.png" width="200px" height="400px" />
    <img alt="Demo 6" src="https://github.com/symbiotdev/react-native-heatmap/blob/main/assets/6.png" width="200px" height="400px" />
    <img alt="Demo 7" src="https://github.com/symbiotdev/react-native-heatmap/blob/main/assets/7.png" width="200px" height="400px" />
    <img alt="Demo 8" src="https://github.com/symbiotdev/react-native-heatmap/blob/main/assets/8.png" width="200px" height="400px" />
  </div>
</div>

___

## [✨ Key Features](#features)

🔥 **Activity Grid** – Clean, familiar visual language  
🎨 **Themeable & Flexible** – Customize color levels, spacing & more  
📆 **Date-Aware** – Renders accurate calendar heatmaps over weeks/months  
📱 **Cross-Platform** – Fully supports:

- iOS & Android
- Web via React Native Web
- Expo & Expo Go

💡 **Use Cases**

- Habit tracking
- Productivity dashboards
- Wellness streaks
- Learning progress (e.g. courses, coding)
- Daily user activity insights

---

## [👩🏿‍💻 Installation](#installation)

```bash
npm install @symbiot.dev/react-native-heatmap date-fns react-native-svg
# or
yarn add @symbiot.dev/react-native-heatmap date-fns react-native-svg

# for web support
npm i react-native-web
# or
yarn add react-native-web
```

---

## [🧩 Components](#components)

The package provides **two** main heatmap components out of the box:

- `MonthlyHeatMap` — Displays activity heatmaps aggregated by month.
- `WeeklyHeatMap` — Displays activity heatmaps aggregated by week.

---

## 📅 `HeatMapDailyProps` – [Daily Data Configuration](#daily)

Provide daily activity data for the heatmap.
Accepts either an array of dates or a record mapping dates to activity counts.

| Property | Type                                           | Description                                               | 🌐 Web | 🍏 iOS | 🤖 Android |
|----------|------------------------------------------------|-----------------------------------------------------------|:------:|:------:|:----------:|
| `data`   | `(Date \| string)[] \| Record<string, number>` | Array of dates or object with date keys and count values. |   ✅    |   ✅    |     ✅      |

---

## 📆 `HeatMapWeeklyProps` – [Weekly Data Configuration](#weekly)

Customize weekly layout and cell content display.
Set which day the week starts on and choose to show date or count inside cells.

| Property       | Type                | Description                                             | 🌐 Web | 🍏 iOS | 🤖 Android |
|----------------|---------------------|---------------------------------------------------------|:------:|:------:|:----------:|
| `weekStartsOn` | `Day`               | Day to start the week (e.g. Sunday or Monday).          |   ✅    |   ✅    |     ✅      |
| `cellText`     | `'date' \| 'count'` | Content shown inside cells: the date or activity count. |   ✅    |   ✅    |     ✅      |

---

> The components is fully customizable, offering a flexible theming system to align with your app’s look and feel. You can fine-tune the color palette, layout behavior, and styling for both light and dark modes.

## 🔥 `HeatMapScheme` – [Color Scheme Configuration](#colorscheme)

```ts
type HeatMapScheme = 'light' | 'dark';
```

Defines the visual scheme used by the heatmap. Useful when supporting multiple themes.

- `light` – Light mode colors
- `dark` – Dark mode colors

```ts
type HeatMapColor = {
  headerTextColor?: string;
  cellDefaultColor?: string;
  cellTextColor?: string;
  cellColor?: Record<number, string>;
  sidebarTextColor?: string;
};
```

Defines the color palette for different parts of the heatmap UI.

| Property           | Type                     | Description                                                         | Web | iOS | Android |
|--------------------|--------------------------|---------------------------------------------------------------------|:---:|:---:|:-------:|
| `headerTextColor`  | `string`                 | Color of the top header labels (e.g. days of the week).             |  ✅  |  ✅  |    ✅    |
| `cellDefaultColor` | `string`                 | Background color used when no activity level is defined.            |  ✅  |  ✅  |    ✅    |
| `cellTextColor`    | `string`                 | Text color inside individual cells (if used).                       |  ✅  |  ✅  |    ✅    |
| `cellColor`        | `Record<number, string>` | Maps activity levels (e.g. 1–5) to specific cell background colors. |  ✅  |  ✅  |    ✅    |
| `sidebarTextColor` | `string`                 | Color for sidebar text (e.g. month or week labels).                 |  ✅  |  ✅  |    ✅    |

## 🎨 `HeatMapThemeProps` – [Theme & Colors](#theme)

Supports global styling with per-scheme overrides (light/dark). The scheme property determines the active theme. You can define a base theme and override specific properties for each mode.

```ts
type HeatMapThemeProps = HeatMapColor & {
  scheme?: HeatMapScheme;
} & {
  [key in HeatMapScheme]?: HeatMapColor;
};
```

## 🎨 `HeatMapStyle` – [Style Customization](#style)

```ts
type HeatMapStyle = {
  scrollStyle?: StyleProp<ViewStyle>;
  headerTextAlign?: TextStyle['textAlign'];
};
```

Defines optional style overrides for layout and header alignment in the heatmap component.
Use this type to customize the scroll container and control how the header text is aligned.

| Property          | Type                     | Description                                                        | Web | iOS | Android |
|-------------------|--------------------------|--------------------------------------------------------------------|:---:|:---:|:-------:|
| `scrollStyle`     | `StyleProp<ViewStyle>`   | Style for the scrollable container that wraps the heatmap grid.    |  ✅  |  ✅  |    ✅    |
| `headerTextAlign` | `TextStyle['textAlign']` | Controls alignment of the header text (`left`, `center`, `right`). |  ✅  |  ✅  |    ✅    |

---

## 📐 `HeatMapDimensionsProps` – [Dimensions & Sizing](#dimensions)

Customize sizing and spacing to perfectly fit your design and layout needs.
Adjust fonts, cell size, gaps, and radius for a tailored heatmap appearance.

| Property              | Type     | Description                                             | 🌐 Web | 🍏 iOS | 🤖 Android |
|-----------------------|----------|---------------------------------------------------------|:------:|:------:|:----------:|
| `headerTextFontSize`  | `number` | Font size for the header text (e.g. days of week).      |   ✅    |   ✅    |     ✅      |
| `headerBottomSpace`   | `number` | Space below the header area.                            |   ✅    |   ✅    |     ✅      |
| `cellSize`            | `number` | Width and height of each heatmap cell.                  |   ✅    |   ✅    |     ✅      |
| `cellRadius`          | `number` | Border radius of each heatmap cell for rounded corners. |   ✅    |   ✅    |     ✅      |
| `cellGap`             | `number` | Gap between individual cells.                           |   ✅    |   ✅    |     ✅      |
| `cellTextFontSize`    | `number` | Font size of the text inside each cell (if any).        |   ✅    |   ✅    |     ✅      |
| `sideBarTextFontSize` | `number` | Font size for the sidebar text (e.g. month labels).     |   ✅    |   ✅    |     ✅      |

---

## 🎛️ `HeatMapControllerProps` – [Controller & Interaction](#controller)

Control interaction and visibility options for the heatmap component.
Toggle press, hover, scrolling behaviors, layout direction, and UI element visibility.

| Property            | Type      | Description                                              | 🌐 Web | 🍏 iOS | 🤖 Android |
|---------------------|-----------|----------------------------------------------------------|:------:|:------:|:----------:|
| `pressable`         | `boolean` | Enables pressing (tap) on heatmap cells.                 |   ✅    |   ✅    |     ✅      |
| `hoverable`         | `boolean` | Enables hover effect on cells (primarily for web).       |   ✅    |   ❌    |     ❌      |
| `scrollable`        | `boolean` | Enables scrolling of the heatmap container.              |   ✅    |   ✅    |     ✅      |
| `rtl`               | `boolean` | Enables right-to-left layout support for RTL languages.  |   ✅    |   ✅    |     ✅      |
| `isHeaderVisible`   | `boolean` | Toggles visibility of the header row (e.g. days labels). |   ✅    |   ✅    |     ✅      |
| `isCellTextVisible` | `boolean` | Toggles visibility of text inside cells.                 |   ✅    |   ✅    |     ✅      |
| `isSidebarVisible`  | `boolean` | Toggles visibility of the sidebar (e.g. month labels).   |   ✅    |   ✅    |     ✅      |

---

## 📝 `HeatMapFormatterProps` – [Text Formatting & Localization](#formatter)

Customize text formatting and localization for headers and sidebars.
Format date labels and apply locale-specific formatting for better internationalization.

| Property            | Type     | Description                                            | 🌐 Web | 🍏 iOS | 🤖 Android |
|---------------------|----------|--------------------------------------------------------|:------:|:------:|:----------:|
| `headerTextFormat`  | `string` | Format string for header text (e.g. days of the week). |   ✅    |   ✅    |     ✅      |
| `sidebarTextFormat` | `string` | Format string for sidebar text (e.g. month labels).    |   ✅    |   ✅    |     ✅      |
| `locale`            | `Locale` | Locale object for date localization (from `date-fns`). |   ✅    |   ✅    |     ✅      |

---

## ⏳ `HeatMapDatetimeProps` – [Date & Time Configuration](#datetime)

Configure the date range and visibility of specific days in the heatmap.
Control which days are displayed and the start/end boundaries of the activity grid.

| Property     | Type    | Description                                | 🌐 Web | 🍏 iOS | 🤖 Android |
|--------------|---------|--------------------------------------------|:------:|:------:|:----------:|
| `startDate`  | `Date`  | The starting date for the heatmap display. |   ✅    |   ✅    |     ✅      |
| `endDate`    | `Date`  | The ending date for the heatmap display.   |   ✅    |   ✅    |     ✅      |
| `hiddenDays` | `Day[]` | Array of days to hide (e.g., weekends).    |   ✅    |   ✅    |     ✅      |

---

## 🎯 `HeatMapActionsProps` – [User Actions & Events](#actions)

Handle user interactions with the heatmap cells, including taps and mouse events.
Useful for adding custom behaviors like tooltips, navigation, or analytics tracking.

| Property       | Type                                                                    | Description                                         | 🌐 Web | 🍏 iOS | 🤖 Android |
|----------------|-------------------------------------------------------------------------|-----------------------------------------------------|:------:|:------:|:----------:|
| `onCellPress`  | `(params: { date: Date; count: number }) => void`                       | Callback fired when a cell is pressed/tapped.       |   ✅    |   ✅    |     ✅      |
| `onMouseEnter` | `(params: { date: Date; x: number; y: number; count: number }) => void` | Callback fired when mouse enters a cell (web only). |   ✅    |   ❌    |     ❌      |
| `onMouseLeave` | `() => void`                                                            | Callback fired when mouse leaves a cell (web only). |   ✅    |   ❌    |     ❌      |

---

### [🌐 **Platform Support**](#support)

- ✅ iOS
- ✅ Android
- ✅ Web
- ✅ Expo & Expo Go

---

### [📦 **Bundle Size**](#size)

Lightweight and fast — see actual size on [Bundlephobia](https://bundlephobia.com/package/@symbiot.dev/react-native-heatmap).

---

### [💬 Contributing](#contributing)

Contributions welcome! Feel free to open issues, discussions, or suggestions.

---

### [🌟 Who's Using This?](#usage)

Using `react-native-heatmap` in your app or product?  
Feel free to share your project — it might be featured in this section!

> ✉️ Open pull request, or reach out directly to get included.

___

### [🚀 Got Ideas or Gaps to Fill?](#ideas)

Know of existing libraries or functionality that could be improved?  
Have an idea for something completely new?

**Symbiot** is ready to take on the challenge — feedback, feature requests, or collaboration ideas are always welcome!

> 🧠 Let’s build better tools together. Start the conversation or contact via [email](mailto:info@symbiot.dev).

___

### [🧾 License](#license)

MIT — Made with ❤️ by [Symbiot](https://symbiot.dev)