DOCSEARCHbyAlgolia
Submit Docs

react-calendar-heatmap

repository·master·Indexed 23 days ago

https://github.com/kevinsqi/react-calendar-heatmap

An SVG-based calendar heatmap component for React, inspired by GitHub's contribution graph. Version 1.10.0 allows developers to visualize data over time with a highly configurable and responsive layout. Key features include customizable date ranges via startDate and endDate, color scaling through the classForValue prop, and support for custom tooltips and interaction handlers.

Tokens
2.9K
Snippets
7
Records
10
Agent score
75%

What's inside react-calendar-heatmap

  1. Basic Usage of CalendarHeatmap

    master

    To use the component, import CalendarHeatmap and its associated CSS styles. The component expands to the size of its container. You must provide a values array where each object contains a date (Date object, parseable string, or millisecond timestamp) and a count.

    import CalendarHeatmap from 'react-calendar-heatmap';
import 'react-calendar-heatmap/dist/styles.css';

// ...

<CalendarHeatmap
  startDate={new Date('2016-01-01')}
  endDate={new Date('2016-04-01')}
  values={[
    { date: '2016-01-01', count: 12 },
    { date: '2016-01-22', count: 122 },
    { date: '2016-01-30', count: 38 },
    // ...and so on
  ]}
/>

  4. Develop the demo site locally

    master

    To develop the demo site in sync with the react-calendar-heatmap package, you must link the package to the demo directory.

    1. In the parent react-calendar-heatmap directory, run yarn link and yarn start.
    2. In the demo directory, run yarn link react-calendar-heatmap and yarn start.

    The demo site will be available at localhost:3000. Changes made to the react-calendar-heatmap source code will be reflected on the demo site.

    # In the parent react-calendar-heatmap directory
yarn link
yarn start

# In the demo directory
yarn link react-calendar-heatmap
yarn start

  6. Configure colors using classForValue

    master

    To implement a color scale (like GitHub's contribution graph), use the classForValue prop. This function receives the value object and returns a CSS class name. You then define the fill color for these classes in your CSS.

    <CalendarHeatmap
  values={[
    { date: '2016-01-01', count: 1 },
    { date: '2016-01-03', count: 4 },
    { date: '2016-01-06', count: 2 },
    // ...and so on
  ]}
  classForValue={(value) => {
    if (!value) {
      return 'color-empty';
    }
    return `color-scale-${value.count}`;
  }}
/>
    .react-calendar-heatmap .color-scale-1 { fill: #d6e685; }
.react-calendar-heatmap .color-scale-2 { fill: #8cc665; }
.react-calendar-heatmap .color-scale-3 { fill: #44a340; }
.react-calendar-heatmap .color-scale-4 { fill: #1e6823; }

  7. Reference: CalendarHeatmap Props

    master

    The following props are available for the CalendarHeatmap component:

    | Name | Type | Description |
| ---- | ---- | ----------- |
| `values` | **Required**, Array of Object | Required array of objects which each have a date property, which can be a Date object, parseable string, or millisecond timestamp. Example: `[{ date: '2016-01-01', count: 6 }]` |
| `startDate` | String, Number, or Date | Start of date range. |
| `endDate` | String, Number, or Date | End of date range - a Date object, parseable string, or millisecond timestamp. |
| `showMonthLabels` | Boolean | Toggle for removing month labels. |
| `showWeekdayLabels` | Boolean | Toggle for removing weekday labels. |
| `showOutOfRangeDays` | Boolean | Toggle display of extra days in week that are past endDate and before beginning of range. |
| `horizontal` | Boolean | Whether to orient horizontally or vertically. Can be used in combination with numDays/endDate to show just the current month. |
| `gutterSize` | Number | Size of gutters relative to squares. |
| `onClick` | Function | Callback to invoke when a square is clicked, e.g. `(value) => alert(value)` |
| `onMouseOver` | Function | Callback to invoke when mouse pointer is over a square, e.g. `(event, value) => console.log(event, value)` |
| `onMouseLeave` | Function | Callback to invoke when mouse pointer leaves a square, e.g. `(event, value) => console.log(event, value)` |
| `titleForValue` | Function | Function to determine each square's title attribute, for generating 3rd party hover tooltips (may also need to configure tooltipDataAttrs). Example: `(value) => `Date is ${value.date}`` |
| `tooltipDataAttrs` | Object or Function | Set data attributes for all squares, for generating 3rd party hover tooltips. Either an object like `{ 'data-tooltip': 'tooltip' }` or a function like `(value) => { return { 'data-tooltip': 'Tooltip: ' + value } }` |
| `classForValue` | Function | Callback for determining CSS class to apply to each value, e.g. `(value) => (value.count > 0 ? 'blue' : 'white')`. |
| `monthLabels` | Array of String | An array with 12 strings representing the text from January to December, e.g. `['01', '02', ..., '12']` |
| `weekdayLabels` | Array of String | An array with 7 strings representing the text from Sunday to Saturday |
| `transformDayElement` | Function | A function to further transform generated svg element for a single day. Can be used to attach event handlers, add tooltips and more. Example: `(element, value, index) => React.cloneElement(element, { title: value.date })` |

  8. Customize day styling and tooltips

    master

    You can control how individual days look and how they interact with 3rd party tooltip libraries using classForValue and tooltipDataAttrs.

    To change the CSS class based on the value:

    classForValue={(value) => (value.count > 5 ? 'high-activity' : 'low-activity')}

    To add data attributes for tooltips (like Bootstrap or Tippy.js):

    // As an object
tooltipDataAttrs={{ 'data-toggle': 'tooltip', 'data-placement': 'top' }}

// Or as a function for dynamic attributes
tooltipDataAttrs={(value) => ({
  'data-bs-toggle': 'tooltip',
  'data-bs-title': `Count: ${value.count}`
})}

  9. Use the CalendarHeatmap component

    master
    The CalendarHeatmap component renders an SVG-based heatmap of activity over a period of time. It accepts a values array where each object must contain a date (string, number, or Date object). You can control the date range using startDate and endDate, or by providing numDays (deprecated) to show a specific number of days back from the endDate.

  10. Configure CalendarHeatmap props

    master

    The CalendarHeatmap component is highly configurable via props. Key categories include:

    Date Range

    • values: (Required) Array of objects with a date property.
    • startDate: Start of the date range (String, Number, or Date).
    • endDate: End of the date range (String, Number, or Date). Defaults to new Date().
    • numDays: (Deprecated) Number of days back from endDate to show. Use startDate instead.
    • showOutOfRangeDays: Boolean. Whether to render squares for extra days in the week before startDate or after endDate.

    Layout & Appearance

    • horizontal: Boolean. If true, the heatmap is oriented horizontally. Defaults to true.
    • gutterSize: Number. Space between squares. Defaults to 1.
    • showMonthLabels: Boolean. Whether to show month labels. Defaults to true.
    • showWeekdayLabels: Boolean. Whether to show weekday labels. Defaults to false.
    • monthLabels: Array of 12 strings for month names. Defaults to MONTH_LABELS.
    • weekdayLabels: Array of 7 strings for weekday names. Defaults to DAY_LABELS.

    Styling & Interaction

    • classForValue: Function (value) => string. Returns a CSS class for a given value. Defaults to (value) => (value ? 'color-filled' : 'color-empty').
    • titleForValue: Function (value) => string. Returns text for the <title> element (native tooltip).
    • tooltipDataAttrs: Object or Function (value) => object. Data attributes to add to the <rect> (e.g., for Bootstrap tooltips).
    • transformDayElement: Function (rect, value, index) => ReactElement. Allows custom transformation of the day's SVG element.
    • onClick: Function (value) => void.
    • onMouseOver: Function (event, value) => void.
    • onMouseLeave: Function (event, value) => void.