react-activity-calendar

Tooltips are now integrated directly into the package using Floating UI as a "headless" component. This means they do not come with predefined styles, giving you full control over their appearance.

To use tooltips, you have two options:

1. Use default styles: Import the default styles provided by the package.
2. Custom styles: Add your own custom CSS to style the headless components.

To use the React Activity Calendar component in your project, install it using npm:

npm install react-activity-calendar

Version 3 introduces several breaking changes, including a shift to pure ESM and changes to component props. Follow these key migration steps:

1. Switch to ESM: The package is now a pure ESM package.
2. Update Imports: The default export has been removed. You must now use the named export ActivityCalendar.
3. Handle Loading States: The <Skeleton /> component has been removed. To show a loading state, render the <ActivityCalendar /> with empty data and the loading prop.
4. Update Tooltips: Tooltips are now integrated using Floating UI as a headless component. You must either import the provided default styles or provide your own custom CSS.

// Old (v2)
import ActivityCalendar from 'react-activity-calendar';

// New (v3)
import { ActivityCalendar } from 'react-activity-calendar';

If the calendar fails to render in your specific React framework environment, check the official framework examples repository. This project supports Server Side Rendering (SSR) and provides working examples for:

• Astro
• Next.js
• Remix
• Vite

Reference: Framework examples

The ActivityCalendar component renders a heatmap based on activity data.

Data Format

The component expects an array of objects. Each object must represent an activity on a specific date and include a level value. The level must fall within the bounds defined by the minLevel and maxLevel props (which default to [0, 4]).

Each data object should contain:

• date: A string representing the date.
• count: The number of activities (optional, depending on your use case).
• level: The intensity/level of activity for that date.

import { ActivityCalendar } from 'react-activity-calendar'

const data = [
  {
    date: '2024-06-23',
    count: 2,
    level: 1,
  },
  {
    date: '2024-08-02',
    count: 16,
    level: 4,
  },
  {
    date: '2024-11-29',
    count: 11,
    level: 3,
  },
]

function Calendar() {
  return <ActivityCalendar data={data} />
}

The theme prop allows you to define colors for different activity levels across light and dark color schemes.

• Automatic Scaling: If you provide only two colors (the minimum and maximum intensity), the component calculates the intermediate colors automatically.
• Explicit Themes: If you provide an explicit array of colors, the count must match the number of activity levels defined by minLevel and maxLevel.
• Negative Levels: If your data includes negative activity levels, you can provide three colors representing the negative, zero, and positive levels to calculate a corresponding scale.

Example of providing two colors per scheme for automatic scaling:

<ActivityCalendar
  data={data}
  theme={{
    light: ['hsl(0, 0%, 92%)', 'firebrick'],
    dark: ['#333', 'rgb(214, 16, 174)'],
  }}
/>

You can fine-tune the Tooltip component using the following configuration options:

• placement: Controls where the tooltip appears. Uses standard @floating-ui/react placement strings.
• offset: Sets the gap between the trigger and the tooltip. Defaults to 4.
• hoverRestMs: Controls the 'exit' delay. A higher value keeps the tooltip visible longer after the user stops hovering. Defaults to 150ms.
• withArrow: A boolean flag to toggle the visibility of the FloatingArrow component.
• transitionStyles: Allows passing custom transition configurations for smooth entry/exit animations.

When upgrading from v2 to v3, the following API changes must be addressed:

Imports

• The default export is removed. Use the named export ActivityCalendar.

Props

• eventHandlers: Removed. To attach event handlers, use the renderBlock prop in combination with React.cloneElement().
• totalCount: Removed. Overriding the total count is no longer supported.
• hideColorLegend $\rightarrow$ Renamed to showColorLegend.
• hideMonthLabels $\rightarrow$ Renamed to showMonthLabels.
• hideTotalCount $\rightarrow$ Renamed to showTotalCount.

Components

• <Skeleton />: Removed. Use the following pattern for loading states:

  <ActivityCalendar data={[]} loading />

// Loading state pattern in v3
<ActivityCalendar data={[]} loading />

The createTheme utility performs strict validation on your input. Common errors include:

• Color count mismatch: theme.light must contain exactly 2 or 3 or [N] colors. This happens if the number of colors provided does not match the 2-color (pair), 3-color (triple), or the total number of levels defined by minLevel and maxLevel.
• Invalid color format: Invalid color "[color]" passed. All provided colors must be valid CSS color formats (e.g., hex, hsl, rgb, named colors). This is validated using CSS.supports('color', color) in supported environments.
• Missing modes: The theme object must contain at least one of the fields light and dark.

The renderBlock prop is a render function that allows you to wrap or replace the default SVG activity blocks. This is useful for adding event handlers (like onClick) or wrapping the block in a link.

Use React.cloneElement if you need to pass additional props to the original SVG element.

<ActivityCalendar
  data={data}
  renderBlock={(block, activity) => (
    <a href={`/activity/${activity.date}`} style={{ cursor: 'pointer' }}>
      {React.cloneElement(block, { onClick: () => console.log(activity.date) })}
    </a>
  )}
/>

The tooltips prop allows you to customize the information displayed when hovering over activity blocks or the color legend.

• tooltips.activity: Configures tooltips for activity blocks. Requires a text function that returns a string based on the Activity object.
• tooltips.colorLegend: Configures tooltips for the color legend. Requires a text function that returns a string based on the activity level.

Both configurations support standard tooltip options like placement, hoverRestMs, offset, transitionStyles, and withArrow.