figma-contribution-chart

GitHub-style contribution heatmap chart for Figma file activity. Visualize your team's design contributions with beautiful, customizable charts.

Features

• 🎨 5 Color Presets - Green (GitHub-style), Purple, Blue, Orange, Monochrome
• 🌓 Light/Dark Mode - Automatic, light, or dark theme support
• 🔷 4 Cell Shapes - Square, GitHub-style, Rounded, Circle
• 📏 3 Size Presets - Small, Medium, Large
• 📅 Time Ranges - Last 30 days, 90 days, or 1 year
• 🎯 Fully Typed - Written in TypeScript with complete type definitions
• ⚡ Zero Dependencies - Only peer dependencies on React
• 🎭 CSS Variables - Easy theming with CSS custom properties

Installation

npm install figma-contribution-chart
# or
pnpm add figma-contribution-chart
# or
yarn add figma-contribution-chart

Quick Start

1. Import the CSS

Import the CSS in your app's root layout or main entry file:

// app/layout.tsx or _app.tsx
import 'figma-contribution-chart/css';

2. Use the Component

'use client';

import { ContributionChart } from 'figma-contribution-chart';

export default function MyChart() {
  const data = {
    weeks: [
      {
        days: [
          { date: '2024-01-01', count: 3, level: 2 },
          { date: '2024-01-02', count: 5, level: 3 },
          // ... more days
        ],
      },
      // ... more weeks
    ],
    totalContributions: 150,
    maxDailyCount: 8,
  };

  return <ContributionChart data={data} />;
}

Usage with Figma API (Next.js)

For Next.js applications, use the built-in Figma API integration:

1. Set Environment Variables

# .env.local
FIGMA_ACCESS_TOKEN=your_figma_token_here

2. Create API Route

// app/api/figma/activity/route.ts
import { createFigmaActivityHandler } from 'figma-contribution-chart/next';

export const GET = createFigmaActivityHandler();

3. Fetch and Display

'use client';

import { useState, useEffect } from 'react';
import { ContributionChart } from 'figma-contribution-chart';
import type { ContributionData } from 'figma-contribution-chart';

export default function FigmaActivity() {
  const [data, setData] = useState<ContributionData | null>(null);

  useEffect(() => {
    fetch('/api/figma/activity?fileKey=YOUR_FILE_KEY')
      .then((res) => res.json())
      .then(setData);
  }, []);

  if (!data) return <div>Loading...</div>;

  return <ContributionChart data={data} color="green" mode="auto" />;
}

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | data | ContributionData | required | Chart data with weeks and days | | color | 'green' \| 'purple' \| 'blue' \| 'orange' \| 'monochrome' \| ChartTheme | 'green' | Color preset or custom theme | | mode | 'light' \| 'dark' \| 'auto' | 'auto' | Display mode | | shape | 'square' \| 'github' \| 'rounded' \| 'circle' | 'github' | Cell shape | | size | 'sm' \| 'md' \| 'lg' | 'md' | Chart size | | range | '30d' \| '90d' \| '1y' | '1y' | Time range to display | | showDayLabels | boolean | true | Show day of week labels | | showMonthLabels | boolean | true | Show month labels | | showLegend | boolean | true | Show color legend | | showTotalCount | boolean | true | Show total count text | | tooltip | (day: DayData) => string | Default formatter | Custom tooltip formatter | | className | string | - | Additional CSS class | | style | CSSProperties | - | Inline styles |

Examples

Different Color Presets

<ContributionChart data={data} color="purple" />
<ContributionChart data={data} color="blue" />
<ContributionChart data={data} color="orange" />
<ContributionChart data={data} color="monochrome" />

Cell Shapes

<ContributionChart data={data} shape="square" />
<ContributionChart data={data} shape="github" />
<ContributionChart data={data} shape="rounded" />
<ContributionChart data={data} shape="circle" />

Sizes

<ContributionChart data={data} size="sm" />
<ContributionChart data={data} size="md" />
<ContributionChart data={data} size="lg" />

Time Ranges

<ContributionChart data={data} range="30d" />
<ContributionChart data={data} range="90d" />
<ContributionChart data={data} range="1y" />

Custom Tooltip

<ContributionChart
  data={data}
  tooltip={(day) => `${day.count} contributions on ${day.date}`}
/>

Custom Theme

const customTheme = {
  light: {
    level0: '#f0f0f0',
    level1: '#c6e48b',
    level2: '#7bc96f',
    level3: '#239a3b',
    level4: '#196127',
    textColor: '#24292e',
    textMutedColor: '#586069',
  },
  dark: {
    level0: '#161b22',
    level1: '#0e4429',
    level2: '#006d32',
    level3: '#26a641',
    level4: '#39d353',
    textColor: '#c9d1d9',
    textMutedColor: '#8b949e',
  },
};

<ContributionChart data={data} color={customTheme} />

Data Format

ContributionData

interface ContributionData {
  weeks: Week[];
  totalContributions: number;
  maxDailyCount: number;
}

interface Week {
  days: DayData[];
}

interface DayData {
  date: string; // ISO date string (YYYY-MM-DD)
  count: number; // Number of contributions
  level: 0 | 1 | 2 | 3 | 4; // Intensity level
}

Helper Functions

Use the included helper to process raw data:

import { processVersions, computeLevel } from 'figma-contribution-chart';

// Process Figma versions into contribution data
const versions = [
  { created_at: '2024-01-01T10:00:00Z', user: { id: '123' } },
  // ... more versions
];

const data = processVersions(versions, 52); // 52 weeks

// Or manually compute levels
const level = computeLevel(5, 10); // count=5, max=10 → level 2

CSS Customization

Override CSS variables for advanced theming:

.my-custom-chart {
  --fcc-cell-size: 16px;
  --fcc-gap: 4px;
  --fcc-cell-radius: 3px;
  --fcc-level-0: #ebedf0;
  --fcc-level-1: #9be9a8;
  --fcc-level-2: #40c463;
  --fcc-level-3: #30a14e;
  --fcc-level-4: #216e39;
  --fcc-text: #24292e;
  --fcc-text-muted: #586069;
}

Figma API Integration (Advanced)

Manual API Usage

import { figmaFetch, fetchFigmaActivity } from 'figma-contribution-chart/next';

// Low-level fetch
const versions = await figmaFetch('/v1/files/FILE_KEY/versions', {
  headers: { 'X-Figma-Token': process.env.FIGMA_ACCESS_TOKEN },
});

// High-level activity fetch
const activity = await fetchFigmaActivity('FILE_KEY', {
  token: process.env.FIGMA_ACCESS_TOKEN,
  weeks: 52,
});

Error Handling

import { FigmaApiError } from 'figma-contribution-chart/next';

try {
  const data = await fetchFigmaActivity(fileKey, { token });
} catch (error) {
  if (error instanceof FigmaApiError) {
    console.error(`Figma API error: ${error.status} - ${error.message}`);
  }
}

TypeScript

Full TypeScript support with exported types:

import type {
  ContributionData,
  DayData,
  Week,
  ChartTheme,
  ChartModeColors,
  ChartSize,
  CellShape,
  TimeRange,
  TooltipFormatter,
  // Figma API types (from /next)
  FigmaVersion,
  FigmaUser,
} from 'figma-contribution-chart';

Browser Support

• Modern browsers with CSS Grid and CSS Variables support
• React 18+
• Next.js 13+ (for /next exports)

License

MIT © [Your Name]

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Links

• GitHub Repository
• Report Issues
• NPM Package