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.

📱 Demo

✨ Key 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

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

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

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

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

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

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

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.

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

🎨 HeatMapStyle – Style Customization

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

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

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

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

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

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

• ✅ iOS
• ✅ Android
• ✅ Web
• ✅ Expo & Expo Go

📦 Bundle Size

Lightweight and fast — see actual size on Bundlephobia.

💬 Contributing

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

🌟 Who's Using This?

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?

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.

🧾 License

MIT — Made with ❤️ by Symbiot