React Native Heatmap πŸ”₯πŸ“Š

> **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.
NPM downloads NPM version Bundle size Typescript
--- ## [πŸ“± Demo](#demo)

WeeklyHeatMap

Demo 1 Demo 2 Demo 3 Demo 4

MonthlyHeatMap

Demo 5 Demo 6 Demo 7 Demo 8
___ ## [✨ 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` | 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; 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` | 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; 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` | 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)