### Install github-contribution-graph using npm or yarn
Source: https://github.com/ayushsaini00/github-contribution-graph/blob/main/README.md
Instructions for installing the github-contribution-graph package using either npm or yarn package managers.
```bash
npm i github-contribution-graph
```
```bash
yarn add github-contribution-graph
```
--------------------------------
### Draw Contribution Graph with JavaScript
Source: https://github.com/ayushsaini00/github-contribution-graph/blob/main/README.md
Example of how to import and use the `drawContributionGraph` function in JavaScript. It shows basic setup and the need for CSS, either via a link tag or import statement.
```javascript
import drawContributionGraph from "github-contribution-graph";
// for toottip css
//
// or
// import "github-contribution-graph/src/style.css";
drawContributionGraph({
data,
ssr: false,
config: {
graphMountElement: "#app",
},
});
```
--------------------------------
### Example Data Structure for Contribution Graph
Source: https://github.com/ayushsaini00/github-contribution-graph/blob/main/README.md
An example of the expected data format for the `drawContributionGraph` function. The data is structured by year, with each year containing an array of daily contribution objects.
```javascript
const data = {
2023: [
{
done: 12,
not_done: 4, // it's fine if you keep not_done as 0
date: "2023-06-07",
},
{
done: 3,
not_done: 6,
date: "2023-02-25",
},
],
2022: [
{
done: 7,
not_done: 3,
date: "2022-08-01",
},
],
};
```
--------------------------------
### Complete HTML Integration with CSS and JavaScript
Source: https://context7.com/ayushsaini00/github-contribution-graph/llms.txt
This comprehensive example shows how to set up an HTML file, import the necessary CSS for styling, and initialize the contribution graph using JavaScript. It includes sample data spanning multiple years and custom configuration options.
```html
My Activity Dashboard
```
--------------------------------
### Track Activity with Done/Not Done Metrics (JavaScript)
Source: https://context7.com/ayushsaini00/github-contribution-graph/llms.txt
This example demonstrates how to structure contribution data using 'done' and 'not_done' metrics to visualize activity levels. The graph cells are colored based on the number of contributions, providing a visual representation of user engagement.
```javascript
import drawContributionGraph from "github-contribution-graph";
const activityData = {
2023: [
{
done: 0, // No contributions
not_done: 0,
date: "2023-01-01",
},
{
done: 5, // Low activity
not_done: 3,
date: "2023-01-15",
},
{
done: 12, // Medium activity
not_done: 1,
date: "2023-02-10",
},
{
done: 25, // High activity
not_done: 0,
date: "2023-03-20",
},
{
done: 50, // Very high activity
not_done: 0,
date: "2023-04-05",
},
],
};
drawContributionGraph({
data: activityData,
config: {
graphMountElement: "#activity-tracker",
},
});
// Output: Cells colored based on activity level
// - 0 contributions: level0 color (#ebedf0 in standard theme)
// - 1-10: level1 color (#9be9a8)
// - 11-20: level2 color (#40c463)
// - 21-40: level3 color (#30a14e)
// - 41+: level4 color (#216e39)
// Tooltip shows: "25 contributions on Monday, March 20th, 2023"
```
--------------------------------
### Draw Contribution Graph with Basic Configuration (JavaScript)
Source: https://context7.com/ayushsaini00/github-contribution-graph/llms.txt
Renders an interactive SVG contribution graph to a specified DOM element using basic configuration. It takes data and optional configuration options. The output is a visual graph with tooltips on hover, showing contribution details for each day.
```javascript
import drawContributionGraph from "github-contribution-graph";
import "github-contribution-graph/src/style.css";
const data = {
2023: [
{
done: 12,
not_done: 4,
date: "2023-06-07",
},
{
done: 3,
not_done: 6,
date: "2023-02-25",
},
{
done: 15,
not_done: 0,
date: "2023-12-15",
},
],
2022: [
{
done: 7,
not_done: 3,
date: "2022-08-01",
},
{
done: 20,
not_done: 1,
date: "2022-11-23",
},
],
};
drawContributionGraph({
data,
ssr: false,
config: {
graphMountElement: "#app",
},
});
// Output: Renders an interactive SVG contribution graph in the #app element
// Each day cell shows a tooltip on hover: "12 contributions on Wednesday, June 7th, 2023"
```
--------------------------------
### Configure Graph Dimensions for Responsive Layout (JavaScript)
Source: https://context7.com/ayushsaini00/github-contribution-graph/llms.txt
This snippet shows how to set custom dimensions for the contribution graph to adapt to different screen sizes, from compact mobile views to large desktop layouts. It utilizes the graphWidth and graphHeight configuration options.
```javascript
import drawContributionGraph from "github-contribution-graph";
const data = {
2023: [
{ done: 6, not_done: 0, date: "2023-02-14" },
{ done: 19, not_done: 0, date: "2023-08-30" },
],
};
// Compact mobile view
drawContributionGraph({
data,
config: {
graphMountElement: "#mobile-graph",
graphWidth: 360,
graphHeight: 100,
},
});
// Large desktop view
drawContributionGraph({
data,
config: {
graphMountElement: "#desktop-graph",
graphWidth: 1200,
graphHeight: 150,
},
});
// Default dimensions (723x113)
drawContributionGraph({
data,
config: {
graphMountElement: "#default-graph",
},
});
// Output: Three graphs with different viewBox dimensions
// SVG elements are scalable: viewBox="0 0 360 100", viewBox="0 0 1200 150", viewBox="0 0 723 113"
```
--------------------------------
### Handle Invalid Themes and Empty Data (JavaScript)
Source: https://context7.com/ayushsaini00/github-contribution-graph/llms.txt
This snippet illustrates the library's error handling capabilities. It shows how the graph falls back to the 'standard' theme when an invalid theme name is provided and how it gracefully handles empty data by not rendering a graph.
```javascript
import drawContributionGraph from "github-contribution-graph";
const data = {
2023: [
{ done: 10, not_done: 0, date: "2023-04-15" },
],
};
// Invalid theme name - falls back to standard
drawContributionGraph({
data,
config: {
graphMountElement: "#graph",
graphTheme: "nonexistent-theme",
},
});
// Console warning: "The specified graphTheme is not recognized. Defaulting to the 'standard' theme..."
// Output: Graph renders with standard theme (#ebedf0, #9be9a8, #40c463, #30a14e, #216e39)
// Empty data handling
const emptyData = {
2023: [],
};
drawContributionGraph({
data: emptyData,
config: {
graphMountElement: "#empty-graph",
},
});
// Output: Function returns early, no graph rendered (years.length === 0)
```
--------------------------------
### Apply Custom Themes to Contribution Graph (JavaScript)
Source: https://context7.com/ayushsaini00/github-contribution-graph/llms.txt
Enables customization of the contribution graph's appearance by applying predefined or completely custom color schemes. This allows developers to match the graph's aesthetic to their application's design. The output is a graph rendered with the specified color palette.
```javascript
import drawContributionGraph from "github-contribution-graph";
const data = {
2023: [
{ done: 5, not_done: 0, date: "2023-03-10" },
{ done: 18, not_done: 0, date: "2023-07-04" },
{ done: 25, not_done: 0, date: "2023-10-20" },
],
};
// Using built-in Figma theme
drawContributionGraph({
data,
config: {
graphMountElement: "#graph-container",
graphTheme: "figma",
},
});
// Using completely custom theme
drawContributionGraph({
data,
config: {
graphMountElement: "#custom-graph",
graphTheme: "custom",
customTheme: {
level0: "#f0f0f0", // No activity
level1: "#c6e48b", // Low activity
level2: "#7bc96f", // Medium activity
level3: "#239a3b", // High activity
level4: "#196127", // Very high activity
},
},
});
// Output: Renders graphs with custom color palettes
// Figma theme uses: #F24E1E (red), #1ABCFE (blue), #A259FF (purple), #0ACF83 (green)
```
--------------------------------
### Visualize Multi-Year Contribution Data (JavaScript)
Source: https://context7.com/ayushsaini00/github-contribution-graph/llms.txt
Displays contribution data across multiple years in a single visualization, automatically organizing them by year. This feature is useful for tracking long-term activity patterns. The output is a series of stacked SVG graphs, each representing a year, displayed in descending order.
```javascript
import drawContributionGraph from "github-contribution-graph";
const multiYearData = {
2023: [
{ done: 10, not_done: 0, date: "2023-01-15" },
{ done: 22, not_done: 0, date: "2023-06-10" },
{ done: 8, not_done: 0, date: "2023-12-25" },
],
2022: [
{ done: 15, not_done: 0, date: "2022-03-20" },
{ done: 30, not_done: 0, date: "2022-08-12" },
],
2021: [
{ done: 5, not_done: 0, date: "2021-05-05" },
{ done: 12, not_done: 0, date: "2021-11-11" },
],
};
drawContributionGraph({
data: multiYearData,
config: {
graphMountElement: "#timeline",
graphWidth: 900,
graphHeight: 130,
graphTheme: "standard",
},
});
// Output: Renders three separate SVG graphs stacked vertically
// Each graph has id="github-contribution-graph-2023", "...2022", "...2021"
// Years displayed in descending order (2023, 2022, 2021)
```
--------------------------------
### drawContributionGraph API
Source: https://github.com/ayushsaini00/github-contribution-graph/blob/main/README.md
The main function to draw the contribution graph. It accepts data, a server-side rendering flag, and a configuration object.
```APIDOC
## drawContributionGraph(data, ssr, config)
### Description
Renders a contribution graph based on the provided data, SSR flag, and configuration options.
### Method
JavaScript Function Call
### Parameters
#### Data Parameter
- **data** (Object) - Required - The data object containing contribution counts per date, organized by year.
Example:
```json
{
"2023": [
{ "done": 12, "not_done": 4, "date": "2023-06-07" },
{ "done": 3, "not_done": 6, "date": "2023-02-25" }
],
"2022": [
{ "done": 7, "not_done": 3, "date": "2022-08-01" }
]
}
```
#### SSR Parameter
- **ssr** (boolean) - Optional - Defaults to `false`. Set to `true` for server-side rendering.
#### Config Parameter
- **config** (Object) - Optional - Configuration object for customizing the graph.
- **graphWidth** (number) - Optional - Defaults to `723`. The width of the contribution graph.
- **graphHeight** (number) - Optional - Defaults to `113`. The height of the contribution graph.
- **graphMountElement** (string) - Optional - Defaults to `body`. The CSS selector for the element where the graph will be appended.
- **graphTheme** (string) - Optional - Defaults to `standard`. The theme of the graph. Refer to `utils/themes.js` for available themes.
### Request Example
```javascript
import drawContributionGraph from "github-contribution-graph";
// For tooltip CSS
// import "github-contribution-graph/src/style.css";
const graphData = {
2023: [
{ done: 12, not_done: 4, date: "2023-06-07" },
{ done: 3, not_done: 6, date: "2023-02-25" }
],
2022: [
{ done: 7, not_done: 3, date: "2022-08-01" }
]
};
drawContributionGraph(graphData, false, {
graphMountElement: "#app",
graphWidth: 800,
graphTheme: "dark"
});
```
### Response
This function does not return a value directly. It manipulates the DOM to render the graph.
#### Success Response
(DOM manipulation)
#### Response Example
(No direct JSON response; graph is rendered in the DOM)
```
--------------------------------
### Server-Side Rendering (SSR) for Contribution Graph (JavaScript)
Source: https://context7.com/ayushsaini00/github-contribution-graph/llms.txt
Generates an SVG HTML string for server-side rendering frameworks, allowing the contribution graph to be pre-rendered on the server. It accepts data and configuration for dimensions. The output is a string representing the SVG element that can be directly injected into HTML.
```javascript
import drawContributionGraph from "github-contribution-graph";
const data = {
2023: [
{
done: 8,
not_done: 0,
date: "2023-05-15",
},
{
done: 14,
not_done: 2,
date: "2023-09-22",
},
],
};
// In a Next.js page or Express route
export default function ContributionPage() {
const svgString = drawContributionGraph({
data,
ssr: true,
config: {
graphWidth: 800,
graphHeight: 120,
},
});
// Returns: SVG string like "