GitHub Profile Contributions Widget

A React component that displays a GitHub user's contribution graph, styled to match GitHub's public profile. Supports light and dark color schemes.

No Tailwind setup is required in the consuming app. The package ships its own compiled CSS.

Demo

https://github-profile-contributions-widget.theplayroom.dev

Installation

npm install github-profile-contributions-widget

Peer dependencies: react >= 18 and react-dom >= 18.

Usage

import { GitHubContributions } from "github-profile-contributions-widget";

function App() {
  return (
    <GitHubContributions
      username="hugogilmar"
      colorScheme="system" // 'light' | 'dark' | 'system' (default)
    />
  );
}

Styles are included automatically through the component entrypoint. If your toolchain requires explicit CSS imports for third-party packages, import it manually:

import "github-profile-contributions-widget/styles.css";

Props

| Prop | Type | Default | Description | | ------------- | ------------------------------- | ---------- | --------------------------------------- | | username | string | (required) | GitHub username to display | | colorScheme | 'light' \| 'dark' \| 'system' | 'system' | Color scheme for the contribution graph |

Exports

// Component
export { GitHubContributions } from "github-profile-contributions-widget";

// Custom hook (for building your own UI)
export { useContributions } from "github-profile-contributions-widget";

// TypeScript types
export type {
  GitHubContributionsProps,
  UseContributionsResult,
  ContributionDay,
  ContributionWeek,
  ContributionsData,
  ContributionLevel,
  ApiResponse,
} from "github-profile-contributions-widget";

Development

npm install
npm run dev      # Start dev server with demo
npm run build    # Build library to dist/
npm run lint     # Run ESLint

Contributing

Contributions are welcome.

1. Fork the repository and create a feature branch.
2. Install dependencies with npm install.
3. Make your changes and add or update tests when needed.
4. Run checks locally:

npm run lint
npm run test
npm run build

5. Open a pull request with a clear description of what changed and why.

License

MIT