NPM Version License Bundle Size
An interactive GitHub contribution snake game for React. Transform any GitHub contribution heatmap into a playable snake game.
π Live Studio
- 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.
npm install react-github-snake
import { GitHubSnake } from 'react-github-snake'; import 'react-github-snake/style.css'; function App() { return ( <GitHubSnake theme="dark" initialMode="AUTOMODE" initialSpeed={80} /> ); }
| 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. |
The useGitHubSnakeExport hook supports:
theme:'light' | 'dark'radius:'square' | 'sm-rounded' | 'md-rounded' | 'xl-rounded'showHeader:booleanshowLabels:booleanshowLegend:boolean
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> ); }
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>
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
MIT Β© akashtdev.