react-contribution-calendar

!npm !NPM

A GitHub-like contribution calendar component for React, built with Vite and TypeScript. This provides a visual representation of contribution activity, similar to the contribution graph seen on a GitHub profile.

Installation

``bash
$ npm i react-contribution-calendar
`

Demo

- codesandbox

Usage

`jsx
import { ContributionCalendar } from 'react-contribution-calendar'

function App() {
const data = [
{
'2020-04-20': { level: 2 }
},
{
'2023-07-08': { level: 1 },
},
{
'2023-07-09': { level: 4, data: {} },
},
{
'2023-03-31': {
level: 3,
data: {
myKey: 'my data',
},
},
},
]

return (
data={data}
dateOptions={{
start: '2020-04-04',
end: '2023-05-19',
daysOfTheWeek: ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'],
startsOnSunday: true,
includeBoundary: true,
}}
styleOptions={{
theme: 'grass',
cx: 10,
cy: 10,
cr: 2,
}}
visibilityOptions={{
hideDescription: false,
hideMonthLabels: false,
hideDayLabels: false,
}}
onCellClick={(e, data) => console.log(data)}
scroll={false}
/>
)
}
`

APIs

$3

ContributionCalendar is the main component of this library. It takes a data property, which is an array of objects representing the contribution data, and a theme property to customize its appearance.

- data: An array of objects, where each object has a date string(YYYY-MM-DD format) as key, and an InputDataProps object as value. Defaults to [].

- An example data is as follows:
`javascript
const data = [
{
'2023-07-08': {
level: 3,
data: {
myKey: 'my data',
},
},
},
{
'2023-07-09': {
level: 1, // data attribute could be omitted
},
},
]
`

- dateOptions: Optional. Defines options for date.
- start: Optional. The starting date for the calendar to start, defaults to current year's January 1st(YYYY-MM-DD format).
- end: Optional. The ending date for the calendar to end, defaults to current year's December 31st(YYYY-MM-DD format).
- daysOfTheWeek: Optional. The days of the week, which will be the head column of each row. The array should start from Sunday so that you can use with startsOnSunday option correctly. Defaults to ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'].
- startsOnSunday: Optional. Whether to start the calendar on Sunday or not, defaults to true. If set to false, calendar will start on Monday.
- includeBoundary: Optional. Whether to include the boundary cells in the starting or ending date column, defaults to true.
- styleOptions: Optional. Defines options for table or cell's style.
- textColor: Optional. The color of indexes. String color code format, defaults to #1F2328.
- style: Optional. Root styles for the ContributionCalendar.
- theme: Optional. A string that represents a predefined theme name, or an object with custom theme colors. Defaults to grass.
- cx: Optional. The pixel size of width of each cell, defaults to 10.
- cy: Optional. The pixel size of height of each cell, defaults to 10.
- cr: Optional. The pixel size of border radius of each cell, defaults to 2.
- visibilityOptions: Optional. Defines visibility for column or row index visibility.
- hideDescription: Optional. Allows you to hide the description displayed at the bottom of the graph.
- hideMonthLabels: Optional. Allows you to hide the month labels displayed at the top of the graph.
- hideDayLabels: Optional. ALlows you to hide the day labels displayed at the side of the graph.
- scroll: Optional. Whether to show scrollbar or not, defaults to false.
- onCellClick: Optional. An onClick mouse event on each table cell.

$3

createTheme is a helper function to create custom themes. It takes a string representing a predefined theme name or an object containing custom theme colors. This returns a theme object(ThemeProps).

Themes

You can customize the appearance of the with the theme property. We provide several built-in themes.

`javascript
// Replace theme attribute with belows

`

$3

#### empty

#### grass

#### cherry

#### cherry_blossom

#### pink

#### ocean

#### sky

#### halloween

#### winter

#### purquoise

#### mustard

#### gray

#### vomit

#### neonpunk

#### citypop

#### coral

#### emoji_positive

#### emoji_negative

$3

#### dark_empty

#### dark_grass

#### dark_cherry

#### dark_cherry_blossom

#### dark_pink

#### dark_ocean

#### dark_sky

#### dark_halloween

#### dark_winter

#### dark_purquoise

#### dark_mustard

#### dark_gray

#### dark_vomit

#### dark_neonpunk

#### dark_citypop

#### dark_coral

$3

`javascript
import { ContributionCalendar, createTheme } from 'react-contribution-calendar'

function App() {
/ Define your custom theme /
const customTheme = createTheme({
level0: '#ebedf0',
level1: '#9be9a8',
level2: '#40c463',
level3: '#30a14e',
level4: '#216e39',
})

return
}
`

Or you can set theme properties directly,

`javascript
import { ContributionCalendar } from 'react-contribution-calendar'

function App() {
return (
styleOptions={{
theme: {
/ Assign theme properties directly /
level0: '#ebedf0',
level1: '#9be9a8',
level2: '#40c463',
level3: '#30a14e',
level4: '#216e39',
}
}}
/>
)
}
`

And say if you'd like to set text theme like emoji, then you could add isTextTheme property as follows:

`javascript
import { ContributionCalendar } from 'react-contribution-calendar'

function App() {
return (
styleOptions={{
theme: {
isTextTheme: true, // <--- Must be added if it's a text theme.
level0: '🙂',
level1: '🤔',
level2: '😎',
level3: 'A',
level4: 'B',
}
}}
/>
)
}
``