github-contrib-graph

github-contribution-graph

A lightweight, customizable GitHub contribution graph widget for any website.

Installation

npm install github-contribution-graph

Quick Start

React

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

function App() {
  return (
    <GitHubContributionGraph
      username="octocat"
      theme="midnight"
      onDataLoaded={(data) => console.log('Loaded!', data)}
    />
  );
}

Vanilla JavaScript

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

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

widget.render();

Script Tag (CDN)

<link rel="stylesheet" href="https://unpkg.com/github-contribution-graph/dist/gh.css">
<div id="gh" data-login="octocat"></div>
<script src="https://unpkg.com/github-contribution-graph/dist/browser.global.js"></script>

React API

GitHubContributionGraph

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

<GitHubContributionGraph
  username="octocat"           // Required: GitHub username
  apiEndpoint="..."            // Optional: Custom API endpoint
  theme="default"              // Optional: Theme preset or custom config
  showHeader={true}            // Optional: Show contribution count header
  showFooter={true}            // Optional: Show legend footer
  showThumbnail={true}         // Optional: Show GitHub attribution
  className="my-class"         // Optional: CSS class
  style={{ margin: 20 }}       // Optional: Inline styles
  onDataLoaded={(data) => {}}  // Optional: Callback when data loads
  onError={(error) => {}}      // Optional: Callback on error
  onLoading={(loading) => {}}  // Optional: Callback on loading state change
/>

useContributionData Hook

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

function CustomGraph() {
  const { data, loading, error, refetch } = useContributionData('octocat', {
    apiEndpoint: 'https://custom-api.com', // Optional
    autoFetch: true,                        // Optional: default true
  });

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

  return (
    <div>
      <p>Total: {data?.contributionsCollection.contributionCalendar.totalContributions}</p>
      <button onClick={refetch}>Refresh</button>
    </div>
  );
}

Vanilla JS API

GitHubContributionWidget

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

const widget = new GitHubContributionWidget({
  username: 'octocat',           // Required: GitHub username
  container: '#my-graph',        // Optional: CSS selector or HTMLElement
  apiEndpoint: '...',            // Optional: Custom API endpoint
  theme: 'void',                 // Optional: Theme preset or custom config
  showHeader: true,              // Optional: Show contribution count header
  showFooter: true,              // Optional: Show legend footer
  showThumbnail: true,           // Optional: Show GitHub attribution
  onDataLoaded: (data) => {},    // Optional: Callback when data loads
  onError: (error) => {},        // Optional: Callback on error
});

// Methods
await widget.render();           // Render the widget
await widget.refresh();          // Refresh data and re-render
const data = widget.getData();   // Get current data
widget.destroy();                // Clear content
await widget.update({ ... });    // Update config and re-render

Themes

Built-in theme presets:

• default - GitHub's default dark theme
• void - Pure black minimalist
• slate - Textured dark grey
• midnight - Deep indigo/purple
• glacier - Clean light theme
• cyber - Neon green matrix style

Custom Theme

const widget = new GitHubContributionWidget({
  username: 'octocat',
  theme: {
    bgColor: '#1a1a2e',
    textColor: '#eaeaea',
    cellLevel0: '#16213e',
    cellLevel1: '#0f3460',
    cellLevel2: '#533483',
    cellLevel3: '#e94560',
    cellLevel4: '#ff6b6b',
    borderColor: '#0f3460',
  },
});

Self-Hosting the API

By default, the widget uses the hosted API at github-contribution-graph.netlify.app. To self-host:

• Clone the repository
• Deploy to Netlify (or similar)
• Set GITHUB_TOKEN environment variable (needs read:user scope)
• Use the apiEndpoint option to point to your deployment

Browser Support

• Modern browsers (ES2020+)
• Node.js 18+

License

Apache-2.0