github-contribution-graph

github-contrib-graph

A lightweight, customizable GitHub contribution graph widget for React, vanilla JavaScript, and plain HTML pages.

Package name: github-contrib-graph. Repository name: github-contribution-graph. The npm package named github-contribution-graph is a different package.

Features

React component and data-fetching hook
Vanilla JavaScript widget class
Script-tag browser bundle for static sites
Built-in dark and light themes
Custom theming through props or CSS variables
Class hooks for every major rendered element
Per-day class, style, attribute, tooltip, and content render hooks
Replaceable header, footer legend, and GitHub attribution
Fully custom React rendering when you only want the package to fetch data
Hosted API by default, with support for your own API endpoint
TypeScript definitions for all public APIs

Installation

npm install github-contrib-graph

Quick Start

React

import { GitHubContributionGraph } from 'github-contrib-graph/react';
import 'github-contrib-graph/styles.css';

export function ProfileActivity() {
  return (
    <GitHubContributionGraph
      username="octocat"
      theme="midnight"
      onDataLoaded={(data) => {
        console.log(data.contributionsCollection.contributionCalendar.totalContributions);
      }}
    />
  );
}

Vanilla JavaScript

import { GitHubContributionWidget } from 'github-contrib-graph/vanilla';
import 'github-contrib-graph/styles.css';

const widget = new GitHubContributionWidget({
  username: 'octocat',
  container: '#my-graph',
  theme: 'void',
});

await widget.render();

<div id="my-graph"></div>

Script Tag

Use this when you do not have a bundler.

<link rel="stylesheet" href="https://unpkg.com/github-contrib-graph@latest/dist/gh.css">

<div
  id="gh"
  data-login="octocat"
  data-show-thumbnail="true"
  data-show-header="true"
  data-show-footer="true"
></div>

<script src="https://unpkg.com/github-contrib-graph@latest/dist/browser.global.js"></script>

For production pages, pin a version instead of using @latest:

<link rel="stylesheet" href="https://unpkg.com/github-contrib-graph@3.1.1/dist/gh.css">
<script src="https://unpkg.com/github-contrib-graph@3.1.1/dist/browser.global.js"></script>

The browser bundle auto-renders an element with id="gh" and data-login. It also exposes window.renderGitHubWidget() for manual re-rendering after you change data-login.

Data Attributes

Attribute	Default	Description
`data-login`	required	GitHub username to render
`data-show-thumbnail`	`"true"`	Show or hide the GitHub attribution icon
`data-show-header`	`"true"`	Show or hide the contribution total and avatar
`data-show-footer`	`"true"`	Show or hide the Less/More legend

React API

import { GitHubContributionGraph } from 'github-contrib-graph/react';

<GitHubContributionGraph
  username="octocat"
  apiEndpoint="https://your-domain.com/api/ghcg/fetch-data"
  theme="default"
  showHeader={true}
  showFooter={true}
  showThumbnail={true}
  showMonthLabels={true}
  showWeekdayLabels={true}
  showTooltips={true}
  dayLabels={['', 'Mon', '', 'Wed', '', 'Fri', '']}
  footerLabels={{ less: 'Less', more: 'More' }}
  classNames={{ root: 'my-graph-root', dayCell: 'my-day-cell' }}
  dayClassName={({ day }) => (day.contributionCount > 0 ? 'has-activity' : '')}
  dayStyle={({ day }) => ({
    opacity: day.contributionCount === 0 ? '0.45' : '1',
  })}
  dayAttributes={({ day }) => ({
    'aria-label': `${day.contributionCount} contributions on ${day.date}`,
  })}
  tooltipFormatter={({ day, date }) =>
    `${day.contributionCount} contributions on ${date.toLocaleDateString()}`
  }
  monthLabelFormatter={(month) => month.name.slice(0, 3)}
  className="my-graph"
  style={{ margin: 20 }}
  onDataLoaded={(data) => {}}
  onError={(error) => {}}
  onLoading={(isLoading) => {}}
/>;

`useContributionData`

import { useContributionData } from 'github-contrib-graph/react';

function TotalContributions() {
  const { data, loading, error, refetch } = useContributionData('octocat', {
    autoFetch: true,
  });

  if (loading) return <div>Loading...</div>;
  if (error) return <div>{error.message}</div>;

  return (
    <button onClick={refetch}>
      {data?.contributionsCollection.contributionCalendar.totalContributions}
    </button>
  );
}

Vanilla API

import { GitHubContributionWidget } from 'github-contrib-graph/vanilla';

const widget = new GitHubContributionWidget({
  username: 'octocat',
  container: '#my-graph',
  apiEndpoint: 'https://your-domain.com/api/ghcg/fetch-data',
  theme: 'void',
  showHeader: true,
  showFooter: true,
  showThumbnail: true,
  showMonthLabels: true,
  showWeekdayLabels: true,
  showTooltips: true,
  classNames: {
    root: 'profile-graph',
    dayCell: 'profile-graph__day',
  },
  dayStyle: ({ day }) => ({
    transform: day.contributionCount > 20 ? 'scale(1.15)' : 'scale(1)',
  }),
  onDataLoaded: (data) => {},
  onError: (error) => {},
});

await widget.render();
await widget.refresh();
const data = widget.getData();
widget.destroy();
await widget.update({ username: 'another-user' });

Themes

Built-in presets:

default
void
slate
midnight
glacier
cyber

Pass a preset name:

<GitHubContributionGraph username="octocat" theme="cyber" />

Or pass a custom theme object:

const widget = new GitHubContributionWidget({
  username: 'octocat',
  theme: {
    bgColor: '#111111',
    textColor: '#eeeeee',
    cellLevel0: '#222222',
    cellLevel1: '#0e4429',
    cellLevel2: '#006d32',
    cellLevel3: '#26a641',
    cellLevel4: '#39d353',
    borderColor: '#333333',
    fontFamily: 'ui-monospace, SFMono-Regular, Menlo, monospace',
  },
});

You can also override CSS variables directly on the widget root:

.my-graph {
  --gh-bg-color: #000000;
  --gh-text-default-color: #ffffff;
  --gh-cell-level0-color: #111111;
  --gh-border-card-color: #333333;
  --gh-font-default-family: ui-monospace, SFMono-Regular, Menlo, monospace;
}

The rendered root receives the ghContributionGraph class, so styles work even when your container is not #gh.

Customization

The package has layered customization. You can use only the built-in presets, override the default DOM with class and render hooks, or skip the default DOM entirely in React and render your own calendar from the fetched data.

Theme Object

Every theme key can be passed through the theme prop or config option. String values are used as-is. Numeric values are converted to px.

<GitHubContributionGraph
  username="octocat"
  theme={{
    bgColor: '#080c10',
    textColor: '#f4f7fb',
    inactiveTextColor: '#7d8794',
    linkHoverColor: '#8ab4ff',
    cellLevel0: '#18202a',
    cellLevel1: '#163b2a',
    cellLevel2: '#196c3d',
    cellLevel3: '#32a852',
    cellLevel4: '#7ee787',
    cellSize: 13,
    cellGap: 4,
    cellRadius: 4,
    cellBorderColor: 'rgba(255,255,255,0.08)',
    cellOutlineColor: 'transparent',
    tooltipBgColor: '#f4f7fb',
    tooltipTextColor: '#080c10',
    tooltipPadding: '8px 10px',
    tooltipRadius: 8,
    tooltipFontSize: 12,
    borderColor: '#27313d',
    borderWidth: 1,
    cardPadding: 18,
    cardPaddingBlock: 10,
    cardRadius: 10,
    canvasPaddingTop: 8,
    canvasMarginInline: 12,
    headerHeight: 28,
    headerMarginBottom: 8,
    headerFontSize: 14,
    avatarSize: 24,
    footerPadding: '8px 32px',
    footerFontSize: 12,
    fontFamily: 'Inter, ui-sans-serif, system-ui, sans-serif',
  }}
/>

The matching CSS variables are:

Theme key	CSS variable
`bgColor`	`--gh-bg-color`
`textColor`	`--gh-text-default-color`
`inactiveTextColor`	`--gh-text-inactive-color`
`linkHoverColor`	`--gh-link-hover-color`
`cellLevel0` - `cellLevel4`	`--gh-cell-level0-color` - `--gh-cell-level4-color`
`cellSize`	`--gh-cell-size`
`cellGap`	`--gh-cell-gap`
`cellRadius`	`--gh-cell-radius`
`cellBorderColor`	`--gh-cell-border-color`
`cellOutlineColor`	`--gh-cell-outline-color`
`tooltipBgColor`	`--gh-cell-info-bg-color`
`tooltipTextColor`	`--gh-tooltip-text-color`
`tooltipPadding`	`--gh-tooltip-padding`
`tooltipRadius`	`--gh-tooltip-radius`
`tooltipFontSize`	`--gh-tooltip-font-size`
`borderColor`	`--gh-border-card-color`
`borderWidth`	`--gh-border-card-width`
`cardPadding`	`--gh-card-padding`
`cardPaddingBlock`	`--gh-card-padding-block`
`cardRadius`	`--gh-card-radius`
`canvasPaddingTop`	`--gh-canvas-padding-top`
`canvasMarginInline`	`--gh-canvas-margin-inline`
`headerHeight`	`--gh-header-height`
`headerMarginBottom`	`--gh-header-margin-bottom`
`headerFontSize`	`--gh-header-font-size`
`avatarSize`	`--gh-avatar-size`
`footerPadding`	`--gh-footer-padding`
`footerFontSize`	`--gh-footer-font-size`
`fontFamily`	`--gh-font-default-family`

Labels, Tooltips, Classes, And Cells

<GitHubContributionGraph
  username="octocat"
  showMonthLabels
  showWeekdayLabels
  showTooltips
  dayLabels={['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat']}
  footerLabels={{ less: 'Quiet', more: 'Busy' }}
  classNames={{
    root: 'activity',
    header: 'activity__header',
    total: 'activity__total',
    profile: 'activity__profile',
    profileLink: 'activity__profile-link',
    avatar: 'activity__avatar',
    card: 'activity__card',
    canvas: 'activity__canvas',
    table: 'activity__table',
    monthLabel: 'activity__month',
    dayLabel: 'activity__weekday',
    dayCell: 'activity__day',
    tooltip: 'activity__tooltip',
    footer: 'activity__footer',
    footerLegend: 'activity__legend',
    thumbnail: 'activity__thumbnail',
    thumbnailLink: 'activity__thumbnail-link',
  }}
  dayClassName={({ day }) =>
    day.contributionCount >= 10 ? 'activity__day--hot' : undefined
  }
  dayStyle={({ day }) => ({
    opacity: day.contributionCount === 0 ? '0.35' : '1',
    borderRadius: day.contributionCount >= 10 ? 6 : 2,
  })}
  dayAttributes={({ day }) => ({
    'aria-label': `${day.contributionCount} contributions on ${day.date}`,
    'data-busy': day.contributionCount >= 10,
  })}
  tooltipFormatter={({ day, date, username }) =>
    `${username} made ${day.contributionCount} contributions on ${date.toLocaleDateString()}`
  }
  monthLabelFormatter={(month) => month.name.toUpperCase()}
/>

Every day cell also receives these default attributes, which makes CSS-only custom designs straightforward:

.activity__day[data-level='FOURTH_QUARTILE'] {
  box-shadow: 0 0 0 2px color-mix(in srgb, var(--gh-cell-level4-color), white 20%);
}

.activity__day[data-count='0'] {
  opacity: 0.4;
}

Replace Individual Sections

The default renderer can replace the header, footer, thumbnail, or the contents inside each day cell. These hooks return DOM nodes or strings.

const widget = new GitHubContributionWidget({
  username: 'octocat',
  container: '#my-graph',
  renderHeader: ({ username, totalContributions, user }) => {
    const header = document.createElement('header');
    header.className = 'activity-header';

    const avatar = document.createElement('img');
    avatar.src = user.avatarUrl;
    avatar.alt = `${username}'s avatar`;

    const name = document.createElement('strong');
    name.textContent = username;

    const total = document.createElement('span');
    total.textContent = `${totalContributions.toLocaleString()} contributions`;

    header.append(avatar, name, total);
    return header;
  },
  renderDayContents: ({ day }) => {
    const dot = document.createElement('span');
    dot.className = 'activity-dot';
    dot.textContent = day.contributionCount > 0 ? String(day.contributionCount) : '';
    return dot;
  },
  renderFooter: ({ labels }) => {
    const footer = document.createElement('footer');
    footer.textContent = `${labels.less} / ${labels.more}`;
    return footer;
  },
  renderThumbnail: () => null,
});

When using the React component, renderHeader, renderFooter, renderThumbnail, and renderDayContents still belong to the default DOM renderer, so they return DOM nodes. Use the React render prop if you want JSX-level control.

Fully Custom React Render

The render prop lets React users use the package only for fetching and state management. You receive the raw GitHub contribution calendar and can render every pixel yourself.

<GitHubContributionGraph
  username="octocat"
  render={({ data, loading, error, refresh }) => {
    if (loading) return <p>Loading activity...</p>;
    if (error) return <button onClick={refresh}>Retry</button>;

    const calendar = data?.contributionsCollection.contributionCalendar;

    return (
      <section className="activity-board">
        <strong>{calendar?.totalContributions.toLocaleString()} contributions</strong>
        <div className="activity-grid">
          {calendar?.weeks.flatMap((week) =>
            week.contributionDays.map((day) => (
              <span
                key={day.date}
                className="activity-cell"
                data-level={day.contributionLevel}
                title={`${day.contributionCount} on ${day.date}`}
              />
            ))
          )}
        </div>
      </section>
    );
  }}
/>

API Endpoint

By default, the package fetches contribution data from:

https://githubgraph.jigyansurout.com/api/ghcg/fetch-data?login={username}

The response shape matches the GitHub GraphQL contribution calendar:

{
  "user": {
    "avatarUrl": "https://avatars.githubusercontent.com/...",
    "contributionsCollection": {
      "contributionCalendar": {
        "totalContributions": 1234,
        "months": [],
        "weeks": []
      }
    }
  }
}

Use apiEndpoint if you want to run your own backend.

Self-Hosting

This repository includes a Cloudflare Pages Functions backend at functions/api/ghcg/fetch-data.js.

Fork or clone the repository.
Create a GitHub personal access token with enough access to read the contribution calendar you want to show.
Add GITHUB_TOKEN to your Cloudflare Pages environment variables.
Use npm run build as the build command.
Use cf-dist as the Pages output directory.
Deploy with the repository root as the project root so Cloudflare can discover functions/.
Pass your endpoint to the widget:

<GitHubContributionGraph
  username="octocat"
  apiEndpoint="https://your-domain.com/api/ghcg/fetch-data"
/>

Local development:

npm install
echo "GITHUB_TOKEN=your_token" > .env
npm run build
npm run dev

Troubleshooting

Use github-contrib-graph, not github-contribution-graph, when installing from npm.
For script-tag usage, place the <script> after the graph container or call window.renderGitHubWidget() after adding the container.
Make sure data-login or username is a valid GitHub username.
If you self-host, confirm your API returns { "user": ... } and includes CORS headers for browser usage.
If private contributions are missing, check the permissions and visibility available to your GitHub token.

Browser Support

Modern browsers with ES2020 support
Node.js 18+

License

Apache-2.0

Name		Name	Last commit message	Last commit date
parent directory ..
src		src
tests		tests
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
README.md		README.md
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
vitest.config.ts		vitest.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

github-contrib-graph

Features

Installation

Quick Start

React

Vanilla JavaScript

Script Tag

Data Attributes

React API

`useContributionData`

Vanilla API

Themes

Customization

Theme Object

Labels, Tooltips, Classes, And Cells

Replace Individual Sections

Fully Custom React Render

API Endpoint

Self-Hosting

Troubleshooting

Browser Support

License

FilesExpand file tree

github-contribution-graph

Directory actions

More options

Directory actions

More options

Latest commit

History

github-contribution-graph

Folders and files

parent directory

README.md

github-contrib-graph

Features

Installation

Quick Start

React

Vanilla JavaScript

Script Tag

Data Attributes

React API

useContributionData

Vanilla API

Themes

Customization

Theme Object

Labels, Tooltips, Classes, And Cells

Replace Individual Sections

Fully Custom React Render

API Endpoint

Self-Hosting

Troubleshooting

Browser Support

License

`useContributionData`