GitHub Contributions Calendar

A React component to display a GitHub contributions calendar

@grubersjoe on GitHub

 

Made with love by @grubersjoe.

npm versionStar

Installation

npm add react-github-calendar

Then in your code:

import GitHubCalendar from 'react-github-calendar';

<GitHubCalendar username="grubersjoe" />

Component properties

The component uses react-activity-calendar internally, so all its properties are supported. See the documentation.

PropTypeDefaultDescription
usernamestring!A GitHub username (required, obviously).
yearnumber | 'last''last'To be rendered year. Defaults to the last year like on GitHub.
blockMarginnumber4Margin between blocks in pixels.
blockRadiusnumber2Border radius of blocks in pixels.
blockSizenumber12Block size in pixels.
colorScheme'light' | 'dark'Use a specific color scheme instead of the system one.
errorMessagestringMessage to show if fetching GitHub contribution data fails. Only relevant if throwOnError is false.
eventHandlers(event: React.SyntheticEvent)
  => (data: Activity)
  => void
{}Event handlers to register for the SVG <rect> elements that are used to render the calendar days. See this example.
fontSizenumber14Font size for text in pixels.
hideColorLegendbooleanfalseToggle to hide color legend below calendar.
hideMonthLabelsbooleanfalseToggle to hide month labels above calendar.
hideTotalCountbooleanfalseToggle to hide total count below calendar.
labelsLabelsLocalization strings for all calendar labels. See here for details.
loadingbooleanfalseToggle for loading state.
refReact.RefObject<HTMLElement>Ref to access the calendar DOM node.
renderBlock(
  block: BlockElement,
  activity: Activity
) => ReactElement
Render prop for calendar blocks (activities). For example, useful to wrap the element with a tooltip component. Use React.cloneElement to pass additional props to the element if necessary.
renderColorLegend(
  block: BlockElement,
  level: number
) => ReactElement
Render prop for color legend blocks. For example, useful to wrap the element with a tooltip component. Use React.cloneElement to pass additional props to the element if necessary.
showWeekdayLabelsboolean | Array<DayName>falseToggle to show weekday labels left to the calendar. Alternatively, pass a list of ISO 8601 weekday names to show. For example ['mon', 'wed', 'fri'].
styleReact.CSSPropertiesStyle object to pass to component container.
themeThemeInputGitHub theme

Set the calendar colors for the light and dark system color scheme. The color scale for at least one color scheme needs to be specified. For undefined values, the default theme is selected. By default, the calendar will use the currently set system color scheme, but you can enforce a specific color scheme with the colorScheme prop.

Define each color scale explicitly with five colors or pass exactly two colors (lowest and highest intensity) to calculate a single-hue scale. Colors can be specified in any valid CSS format.

See this example

throwOnErrorbooleanfalseWhether to throw an Error if fetching GitHub contribution data fails. Use a React error boundary to handle the error.
totalCountnumberOverwrite the total activity count. Useful in combination with transformData.
transformData(data: Activity[])
  => Activity[]
A function that receives the array of contribution data and that has to return an array with the same data type. See example.
transformTotalCountbooleantrueWhen the transformData property is set, the total contribution count will be calculated based on the transformed data. Set this to false to use the original contribution count for all data.
weekStartnumber0 (Sunday)Index of day to be used as start of week. 0 represents Sunday.

Examples & FAQ

Please refer to the Storybook of the calendar component for interactive examples.

How do I add tooltips?

See tooltip examples how to use the renderBlock prop.

Usage of the transformData prop

You can pass a function as the transformData prop that receives the array of contribution data to manipulate it. The transformation function must meet the following signature:

interface Activity {
  date: string;
  count: number;
  level: 0 | 1 | 2 | 3 | 4;
}

function transformData(data: Array<Activity>): Array<Activity>;

For example, to only show the the contribution data of the last six months you can do the following:

const selectLastHalfYear = contributions => {
  const currentYear = new Date().getFullYear();
  const currentMonth = new Date().getMonth();
  const shownMonths = 6;

  return contributions.filter(activity => {
    const date = new Date(activity.date);
    const monthOfDay = date.getMonth();

    return (
      date.getFullYear() === currentYear &&
      monthOfDay > currentMonth - shownMonths &&
      monthOfDay <= currentMonth
    );
  });
};

// ...
  
<GitHubCalendar 
  username="grubersjoe" 
  transformData={selectLastHalfYear} 
  hideColorLegend
  labels={{
    totalCount: '{{count}} contributions in the last half year',
  }}
/>

 

The total count will be recalculated based on the transformed data. However, you can enforce that the total count of the untransformed data is shown by setting the transformTotalCount to false. The text of total count label below the calendar can be adjusted using the labels.totalCount prop and the {{ count }} placeholder.