A low level and stylable Web Component to display an activity graph.
Here are some demos:
- Raw HTML/DOM demo page with multiple theme examples
- React 18 demo page
- React 19 demo page
- Angular 18 demo page
- Vue.js 3.4 demo page
- Svelte 4.2 demo page
Note
Keep in mind that the themes on the demo page and screenshots are just examples of what can be done. They're not released with this component, you will have to create your own theme.
Here's an example of my 2023 GitHub contribution graph.
Here's an example of my 2024 Serializd stats graph.
Here's an example of my 2024 Monkeytype stats graph.
Here's an example of what could be my 2023 Letterboxd stats graph, if they had such a graph.
This component is published on npm. You can "npm install" it in your project with this command:
npm install @hsablonniere/activity-graph
You can also directly use modern CDNs that exposes npm packages like JSDelivr:
<script type="module" src="https://cdn.jsdelivr.net/npm/@hsablonniere/activity-graph/+esm"></script>
or esm.sh:
<script type="module" src="https://esm.sh/@hsablonniere/activity-graph"></script>
Use the <activity-graph>
custom HTML tag like this:
<activity-graph start-date="2024-01-01" end-date="2024-12-31"></activity-graph>
Attribute | Property | Type | Default |
---|---|---|---|
start-date
| startDate
| string with YYYY-MM-DD format
| A year ago |
First date of the graph | |||
end-date
| endDate
| string with YYYY-MM-DD format
| Today |
Last date of the graph | |||
data
| data
| ActivityGraphData
| null
|
Data object, see Data section below | |||
lang
| lang
| string
| Document language (lang attribute on the html tag) or en if not specified
|
BCP 47 language code used to translate weekday and month headers | |||
week-start-day
| weekStartDay
| number
| 0 (sunday)
|
Number representing the first day of the week, from 0 0 (sunday) to 6 (saturday)
| |||
weekday-headers
| weekdayHeaders
| 'none' | 'long' | 'short' | 'narrow'
| narrow
|
Format used for weekday headers (see DateTimeFormat#weekday) or 'none' to hide them
| |||
month-headers
| monthHeaders
| 'none' | 'long' | 'short' | 'narrow' | 'numeric' | '2-digit'
| short
|
Format used for month headers (see DateTimeFormat#month) or 'none' to hide them
| |||
month-limits
| monthLimits
| 'early' | 'middle' | 'late'
| late
|
When to start/end month headers:
| |||
month-position
| monthPosition
| 'top' | 'bottom'
| top
|
Where to put month headers |
The data can be set as a JavaScript object on the data
property, or as JSON on the data
attribute. It must respect the following type definition:
// Keys must be YYYY-MM-DD date strings
type ActivityGraphData = Record<string, ActivityGraphDataEntry>;
interface ActivityGraphDataEntry {
// Used for the day "cell" inner text
text?: string;
// Used for the day "cell" `title` attribute, for tooltips and accessibility
title?: string;
// Used for the day "cell" `part` attribute, as in CSS shadow part for styling purposes
parts?: Array<string>;
}
Here's an example:
myActivityGraph.data = {
'2024-04-01': {
title: '2 contributions',
parts: ['level-1'],
},
'2024-04-04': {
title: '27 contributions',
parts: ['level-4'],
},
};
By default, the component does not have any styles. You'll have to rely on the different CSS parts and custom properties to create a theme.
Note
- You can rely on the fact that the element has a
display: grid
and use properties likegap
directly on it. - You can have a look at the demos and their respective themes to get some ideas on how to style the component.
Part | Description |
---|---|
weekday-header |
Target any weekday header |
weekday-header--even |
Target even numbered weekday headers |
weekday-header--odd |
Target odd numbered weekday headers |
month-header |
Target any month header |
day |
Target any day "cell" |
Tip
If you want to use a CSS shadow part, you'll need the ::part()
pseudo element like this:
activity-graph::part(month-header) {
text-align: center;
}
Property | Description |
---|---|
var(--activity-graph-month-gap) |
Spacing between months, can be any CSS unit, 0 by default |
I really like this way of visualizing a whole year of data at once. Watching such graphs on GitHub, Serializd or Monkeytype, I grew a need to have a similar dataviz for other services where I track and log stuffs like Letterboxd or fitbit. I wondered how easy it would be to create my own component and that's how I went down this rabbit whole.
In the end, I restarted from scratch 3 times to try different ideas to handle the dates and the CSS grid. It wasn't a simple problem to tackle but I had lots of fun working on this.
I started the project as a vanilla Web Component, without any dependency.
I guess I was wondering how small the final bundle would be, I achied something close to 1.6kb
(minified and compressed).
My code was not that easy to read and I had no support for properties, just attributes.
A few commits later, I quickly realized I was recreating a very dumb, verbose and unefficient version of lit.
That's when I decided to add lit as the only dependency.
In the end, the component code + lit is 6.4kb
(minified and compressed).
I wanted something based on CSS grids without any styles by default so that anyone could reuse it and apply their own theme. At first, you could specify some style properties on the data object but I replaced it with CSS shadow parts to maximize styling in the CSS.
I created this project without looking at the competition but obviously many smart people tried before me.
Mario Hamann also made a Web Component and his approach (a11y, WASM, SSR...) is very interesting!
- GitHub project: https://github.com/mariohamann/activity-graph
- Article: https://mariohamann.com/activity-graph-component
And of course, there are plenty of framework specific components for React, Vue, Svelte:
- https://github.com/Angstboksen/date-activity-graph
- https://github.com/AyushSaini00/github-contribution-graph
- https://github.com/KaranGulve4342/react-github-contributions
- https://github.com/cairongquan/contriGraph
- https://github.com/charpeni/sync-external-contributions
- https://github.com/grubersjoe/react-activity-calendar
- https://github.com/grubersjoe/react-github-calendar
- https://github.com/marcelovicentegc/react-github-heatmap
- https://github.com/razorness/vue3-calendar-heatmap
- https://github.com/scottbedard/svelte-heatmap
- https://github.com/srivenkat13/github-calendar-component
- https://github.com/uiwjs/react-heat-map
- https://github.com/x3388638/github-calendar-graph