gitmap

a react component for visualizing github contributions and heatmap

@torvalds's contributions673 total

Jul

Aug

Sep

Oct

Nov

Dec

Jan

Feb

Mar

Apr

May

Jun

Jul

Mon

Wed

Fri

Less

Installation

bash

npm install @arnabjena007/gitmap

Usage

Import the component and pass the username/contributions, selector range, and values.

tsx

import { Gitmap } from '@arnabjena007/gitmap';
 
export default function App() {
  return (
    <div style={{
      border: '1px solid rgba(255, 255, 255, 0.08)',
      borderRadius: '12px',
      padding: '24px',
    }}>
      <Gitmap
        username="torvalds"
        theme={"default-dark"}
        cellSize={14}
        gap={3}
        shape="rounded"
        showNumbers={false}
        useGradient={false}
      />
    </div>
  );
}

Theming with CSS Variables

For custom CSS/styling, custom keys, reference variables in CSS configuration:

css

.custom-theme {
  --gitmap-level-0: #161b22;
  --gitmap-level-1: #0e4429;
  --gitmap-level-2: #006d32;
  --gitmap-level-3: #26a641;
  --gitmap-level-4: #39d353;
}

Static Themes

Alternatively, color objects can be passed via theme props:

tsx

const customTheme = {
  level0: "#161b22",
  level1: "#0e4429",
  level2: "#006d32",
  level3: "#26a641",
  level4: "#39d353",
};

API Reference

Gitmap Props

Prop	Type	Default	Description
`data`	`ContributionDay[]`	`[]`	Array of contribution data objects containing dates and counts.
`username`	`string`	`undefined`	GitHub username. Used to fetch contributions if data is not provided.
`theme`	`string \| GitmapColors`	`"github-dark"`	Preset theme name or a custom theme object.
`cellSize`	`number`	`12`	Size of each grid cell block in pixels.
`gap`	`number`	`3`	Margin/gap between each cell in pixels.
`rounded`	`boolean`	`true`	Whether grid cells have rounded borders.
`showCounts`	`boolean`	`false`	Whether to display tooltip counts on hover.
`onDayClick`	`(day: ContributionDay) => void`	`undefined`	Callback fired when a contribution day cell is clicked.

ContributionDay

Prop	Type	Default	Description
`date`	`string`	`-`	Expected YYYY-MM-DD Date Format.
`count`	`number`	`0`	Value count for corresponding day.
`level`	`0 \| 1 \| 2 \| 3 \| 4`	`-`	Intensity level for corresponding color.

GitmapColors

Prop	Type	Default	Description
`level0`	`string`	`-`	Hex or RGBA color code for level 0.
`level1`	`string`	`-`	Hex or RGBA color code for level 1.
`level2`	`string`	`-`	Hex or RGBA color code for level 2.
`level3`	`string`	`-`	Hex or RGBA color code for level 3.
`level4`	`string`	`-`	Hex or RGBA color code for level 4.

Customization

Custom configurations can be added using custom table options:

tsx

const customTheme = {
  level0: "#1b1f23",
  level1: "#132b43",
  level2: "#194a7a",
  level3: "#1d6cb0",
  level4: "#2190e3",
};
 
export default function App() {
  return (
    <Gitmap
      username="arnab-jena"
      theme={customTheme}
      cellSize={14}
      gap={4}
      shape="sharp"
      showNumbers={false}
      useGradient={true}
    />
  );
}