react-github-snake

An interactive GitHub contribution snake game for React. Transform any GitHub contribution heatmap into a playable snake game.

👉 Live Studio

Features

• Playable Heatmap: Turn standard GitHub contribution data into an interactive game.
• Automode: Built-in pathfinding that clears the board for you.
• Export Assets: Generate static or animated SVGs for your GitHub profile README.
• Responsive: Dynamically fit columns to container width.
• Zero Dependencies: Lightweight and fast.

Installation

npm install react-github-snake

Quick Start

import { GitHubSnake } from 'react-github-snake';
import 'react-github-snake/style.css';

function App() {
  return (
    <GitHubSnake 
      theme="dark"
      initialMode="AUTOMODE"
      initialSpeed={80}
    />
  );
}

Props

Prop	Type	Default	Description
data	ContributionData	undefined	Manual contribution data object. If not provided, renders an empty board.
theme	'light' | 'dark'	'light'	UI theme preset matching GitHub's aesthetics.
boardWidth	number	53	Number of columns in the game board (max 53).
boardHeight	number	7	Number of rows in the game board (7 days per week).
initialMode	'MANUAL' | 'AUTOMODE'	'MANUAL'	Starting game mode.
initialSpeed	number	100	Delay (ms) between moves.
initialWalls	boolean	false	Enable wall-collision (game over on edge hit).
initialSound	boolean	true	Toggle spatial audio feedback.
initialGrow	boolean	false	Enable snake body growth when eating contributions.
initialShowScore	boolean	true	Show score HUD during gameplay.
initialShowHeader	boolean	true	Show user identity header.
blockSize	number	15	Cell size in pixels.
blockMargin	number	4	Gap between cells in pixels.
responsive	boolean	false	Dynamically fit columns to container width.
columns	number	undefined	Force a specific number of columns (overrides boardWidth).
showLabels	boolean	true	Show month labels above the grid.
showLegend	boolean	true	Show the legend and contribution count.
scrollable	boolean	false	Enable horizontal scrolling for overflow.
labels	GitHubSnakeLabels	undefined	Custom text labels for UI elements.
className	string	''	Additional CSS class for the container.
style	React.CSSProperties	undefined	Inline styles for the container.

Export Options

The useGitHubSnakeExport hook supports:

• theme: 'light' | 'dark'
• radius: 'square' | 'sm-rounded' | 'md-rounded' | 'xl-rounded'
• showHeader: boolean
• showLabels: boolean
• showLegend: boolean

Advanced Usage

For external control or multi-component synchronization, wrap your application in the SnakeProvider and use the useSnakeContext hook.

import { SnakeProvider, GitHubSnake, useSnakeContext } from 'react-github-snake';

function CustomControls() {
  const { startGame, stopGame, gameState } = useSnakeContext();
  return (
    <button onClick={gameState === 'PLAYING' ? stopGame : startGame}>
      {gameState === 'PLAYING' ? 'Stop' : 'Start'}
    </button>
  );
}

function App() {
  return (
    <SnakeProvider initialSpeed={50}>
      <CustomControls />
      <GitHubSnake />
    </SnakeProvider>
  );
}

Exporting

You can programmatically trigger SVG exports using the useGitHubSnakeExport hook. This is perfect for generating assets for your GitHub profile README.

import { SnakeProvider, useGitHubSnakeExport } from 'react-github-snake';
import type { ContributionData } from 'react-github-snake';

function ExportButton({ data }: { data: ContributionData }) {
  const { exportSVG, exportAnimatedSVG } = useGitHubSnakeExport();

  return (
    <div>
      <button onClick={() => exportSVG(data, { theme: 'dark' })}>
        Download Static SVG
      </button>
      <button onClick={() => exportAnimatedSVG(data, { theme: 'dark' })}>
        Download Animated SVG
      </button>
    </div>
  );
}

// Must be wrapped in SnakeProvider
<SnakeProvider>
  <ExportButton data={myContributionData} />
</SnakeProvider>

Development

npm run dev          # Start local demo
npm run check        # Lint and format code
npm run test:run     # Run all tests
npm run build        # Build for production

License

MIT © akashtdev.