React GitHub Calendar

@grubersjoe on GitHub

Made with love by @grubersjoe.

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.

Prop	Type	Default	Description
username	string!		A GitHub username (required, obviously).
year	number \| 'last'	'last'	To be rendered year. Defaults to the last year like on GitHub.
blockMargin	number	4	Margin between blocks in pixels.
blockRadius	number	2	Border radius of blocks in pixels.
blockSize	number	12	Block size in pixels.
colorScheme	'light' \| 'dark'		Use a specific color scheme instead of the system one.
errorMessage	string		Message 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.
fontSize	number	14	Font size for text in pixels.
hideColorLegend	boolean	false	Toggle to hide color legend below calendar.
hideMonthLabels	boolean	false	Toggle to hide month labels above calendar.
hideTotalCount	boolean	false	Toggle to hide total count below calendar.
labels	Labels		Localization strings for all calendar labels. See here for details.
loading	boolean	false	Toggle for loading state.
ref	React.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.
showWeekdayLabels	boolean \| Array<DayName>	false	Toggle to show weekday labels left to the calendar. Alternatively, pass a list of ISO 8601 weekday names to show. For example `['mon', 'wed', 'fri']`.
style	React.CSSProperties		Style object to pass to component container.
theme	ThemeInput	GitHub 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
throwOnError	boolean	false	Whether to throw an `Error` if fetching GitHub contribution data fails. Use a React error boundary to handle the error.
totalCount	number		Overwrite 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.
transformTotalCount	boolean	true	When 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.
weekStart	number	0 (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.