1 GitHub star = 1 new component.

Star the repo
Developer Portfolio

Dev Contributions 3D

GitHub-style contribution matrix in 3D: barely-rounded cubes fly in from the sky and assemble, keep rebuilding, and ripple like water around the cursor; tooltips with date and count. Pass weeks, a URL or use demo data.

githubcontributionscalendarthree3dportfolio
Live Preview

Usage

Copy and paste this code into your React component:

tsx
import { DevContributions } from 'react-component-kit-ui/sections';

{/* npm install three */}
<DevContributions title="A year of commits" src="/api/contributions.json" />

Manual Installation

If you are not using the npm package, create a new file and paste the following code: src/components/sections/DevContributions.tsx + DevContributions.css:

DevContributions.tsx
'use client';

import { useEffect, useMemo, useRef } from 'react';
import { demoContributions, type ContributionWeek } from '../three/contributions-scene';
import './DevContributions.css';

/** class:list โ†’ className */
function cx(...args: unknown[]): string {
  const out: string[] = [];
  const walk = (v: unknown) => {
    if (!v) return;
    if (typeof v === 'string' || typeof v === 'number') out.push(String(v));
    else if (Array.isArray(v)) v.forEach(walk);
    else if (typeof v === 'object') for (const [k, on] of Object.entries(v as Record<string, unknown>)) if (on) out.push(k);
  };
  args.forEach(walk);
  return out.join(' ');
}

/**
 * DevContributions โ€” Full-width 3D contribution matrix (GitHub style, "Keycap" design). Each day is
 * a barely-rounded cube whose height and tone encode activity. On first view the cubes fly in from
 * the sky and from both sides and assemble on a board; afterwards a few keep detaching and flying
 * back, and hovering sends water-like ripples around the cursor. Tooltips show the date and count.
 * Needs the optional `three` peer dependency.
 *
 * Data: pass `weeks` directly, or `src` (a URL returning `{ weeks: [{ days: [{ date, count }] }] }`),
 * or nothing for a deterministic demo year (`seed`).
 *
 * @param {Array<{days: Array<{date: string, count: number}>}>} weeks - Contribution weeks (Sunday first).
 * @param {string} src - URL to fetch the weeks from on the client.
 * @param {number} seed - Demo data seed. Default 7.
 * @param {string} title - Heading above the board (optional).
 * @param {string} summary - Text next to the heading, e.g. "1,284 contributions in the last year".
 * @param {string} locale - Date locale for tooltips. Default 'en-US'.
 * @param {object} labels - { months[12], weekdays[7], weekdaysLong[7], less, more, one, many }.
 * @param {[number, number, number]} thresholds - Upper bounds of levels 1โ€“3. Default [2, 5, 8].
 * @param {boolean} debris - Loose cubes drifting in front of the board. Default true.
 * @param {string} className - Extra class.
 *
 * Accessibility: the board has role="img" with an aria-label summarising the year; the tooltip is
 * mirrored to a polite live region; reduced motion renders the board fully assembled and still.
 */
export interface DevContributionsProps {
  weeks?: ContributionWeek[];
  src?: string;
  seed?: number;
  title?: string;
  summary?: string;
  locale?: string;
  labels?: Partial<{ months: string[]; weekdays: string[]; weekdaysLong: string[]; less: string; more: string; one: string; many: string }>;
  thresholds?: [number, number, number];
  debris?: boolean;
  className?: string;
}

export function DevContributions({ weeks, src, seed = 7, title, summary, locale = 'en-US', labels = {}, thresholds = [2, 5, 8], debris = true, className = '' }: DevContributionsProps) {
  const L = {
    months: ['JAN', 'FEB', 'MAR', 'APR', 'MAY', 'JUN', 'JUL', 'AUG', 'SEP', 'OCT', 'NOV', 'DEC'],
    weekdays: ['SUN', 'MON', 'TUE', 'WED', 'THU', 'FRI', 'SAT'],
    weekdaysLong: ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'],
    less: 'LESS',
    more: 'MORE',
    one: 'contribution',
    many: 'contributions',
    ...labels,
  };
  const data = useMemo(() => weeks ?? (src ? undefined : demoContributions(seed)), [weeks, src, seed]);
  const total = data?.reduce((n, w) => n + w.days.reduce((m, d) => m + d.count, 0), 0);
  const aria = total !== undefined ? `${total.toLocaleString(locale)} ${L.many}` : (summary ?? L.many);

  // 3D contribution matrix: three.js is loaded on demand (optional peer dependency); weeks come from
  // the `weeks` prop, the `src` URL or the demo data. Disposed on unmount.
  const rootRef = useRef<HTMLElement>(null);
  const labelsKey = JSON.stringify(L);
  const thresholdsKey = thresholds.join(',');
  useEffect(() => {
    const root = rootRef.current;
    const canvas = root?.querySelector<HTMLElement>('[data-canvas]');
    const tip = root?.querySelector<HTMLElement>('[data-tip]');
    const a = root?.querySelector<HTMLElement>('[data-tip-a]');
    const b = root?.querySelector<HTMLElement>('[data-tip-b]');
    if (!root || !canvas || !tip || !a || !b) return;
    const live = root.querySelector<HTMLElement>('[data-live]');
    let cancelled = false;
    let dispose: (() => void) | undefined;

    const loadWeeks = async (): Promise<ContributionWeek[]> => {
      if (data) return data;
      if (!src) return demoContributions(seed);
      try {
        const json = await (await fetch(src)).json();
        const w = Array.isArray(json?.weeks) ? (json.weeks as ContributionWeek[]) : [];
        return w.length ? w : demoContributions(seed);
      } catch {
        return demoContributions(seed);
      }
    };

    Promise.all([import('three'), import('three/addons/geometries/RoundedBoxGeometry.js'), import('../three/contributions-scene'), loadWeeks()])
      .then(([THREE, { RoundedBoxGeometry }, { mountContributions }, weeksData]) => {
        if (cancelled) return;
        const fmt = new Intl.DateTimeFormat(locale, { day: 'numeric', month: 'long', year: 'numeric', timeZone: 'UTC' });
        dispose = mountContributions(canvas, THREE, RoundedBoxGeometry, {
          weeks: weeksData,
          months: L.months,
          weekdays: L.weekdays,
          legend: { less: L.less, more: L.more },
          thresholds,
          debris,
          onHover: (info, x, y) => {
            if (!info) {
              tip.classList.remove('is-visible');
              return;
            }
            if (info.kind === 'day') {
              a.textContent = `${info.count.toLocaleString(locale)} ${info.count === 1 ? L.one : L.many}`;
              b.textContent = fmt.format(new Date(`${info.date}T00:00:00Z`));
            } else {
              a.textContent = L.weekdaysLong?.[info.index] ?? '';
              b.textContent = L.weekdays?.[info.index] ?? '';
            }
            tip.style.left = `${x}px`;
            tip.style.top = `${y}px`;
            tip.classList.add('is-visible');
            if (live) live.textContent = `${a.textContent}, ${b.textContent}`;
          },
        });
      })
      .catch((err) => console.warn('[DevContributions] the 3D matrix needs the optional `three` peer dependency.', err));
    return () => {
      cancelled = true;
      dispose?.();
    };
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [data, src, seed, locale, labelsKey, thresholdsKey, debris]);
  return (
    <>
      <section ref={rootRef} className={cx(['dvct', className])} data-dev-contrib data-src={src} data-locale={locale} data-labels={JSON.stringify(L)} data-thresholds={JSON.stringify(thresholds)} data-debris={debris ? '1' : '0'} data-rk-06b22a="">
        {(title || summary) && (
          <div className="dvct__head" data-rk-06b22a="">
            {title && <h2 className="dvct__title" data-rk-06b22a="">{title}</h2>}
            {summary && <p className="dvct__summary" data-rk-06b22a="">{summary}</p>}
          </div>
        )}
        <div className="dvct__viewport" data-rk-06b22a="">
          <div className="dvct__tip" data-tip aria-hidden="true" data-rk-06b22a=""><strong data-tip-a data-rk-06b22a=""></strong><span data-rk-06b22a="">โ€ข</span><span data-tip-b data-rk-06b22a=""></span></div>
          <div className="dvct__canvas" data-canvas role="img" aria-label={aria} data-rk-06b22a=""></div>
        </div>
        <p className="dvct__live" aria-live="polite" data-live data-rk-06b22a=""></p>
      </section>
    </>
  );
}

export default DevContributions;
DevContributions.css
.dvct:where([data-rk-06b22a]) {
  --kc-ink: var(--c-text-1);
  --kc-paper: var(--c-bg);
  --kc-muted: var(--c-text-3);
  position: relative;
  width: 100%;
  overflow: hidden;
  color: var(--c-text-1);
}
.dvct__head:where([data-rk-06b22a]) { max-width: 1040px; margin: 0 auto; padding: 0 clamp(1rem, 3vw, 1.5rem); display: flex; flex-wrap: wrap; align-items: baseline; justify-content: space-between; gap: 0.5rem 1rem; }
.dvct__title:where([data-rk-06b22a]) { margin: 0; font-size: clamp(1.3rem, 3vw, 1.8rem); font-weight: 700; letter-spacing: -0.02em; }
.dvct__summary:where([data-rk-06b22a]) { margin: 0; font-family: var(--font-mono); font-size: 0.75rem; color: var(--c-text-3); }
.dvct__viewport:where([data-rk-06b22a]) { position: relative; height: 380px; max-height: 48vh; user-select: none; touch-action: pan-y; }
.dvct__canvas:where([data-rk-06b22a]) { width: 100%; height: 100%; cursor: grab; }
.dvct__canvas:active:where([data-rk-06b22a]) { cursor: grabbing; }
.dvct__tip:where([data-rk-06b22a]) {
  position: absolute;
  top: 0;
  left: 0;
  z-index: 5;
  display: inline-flex;
  align-items: center;
  gap: 0.55rem;
  padding: 0.55rem 1.1rem;
  border-radius: 4px;
  border: 1.5px solid rgb(255 255 255 / 0.25);
  background: #000;
  color: #fff;
  font-family: var(--font-mono);
  font-size: 0.85rem;
  font-weight: 600;
  white-space: nowrap;
  box-shadow: 0 12px 32px rgb(0 0 0 / 0.45);
  pointer-events: none;
  opacity: 0;
  transform: translate(-50%, -140%);
  transition: opacity 0.15s ease;
}
.dvct__tip:where([data-rk-06b22a]) span:first-of-type:where([data-rk-06b22a]) { color: #777; }
.dvct__tip:where([data-rk-06b22a]) span:last-child:where([data-rk-06b22a]) { color: #e5e7eb; font-weight: 500; }
.dvct__tip.is-visible:where([data-rk-06b22a]) { opacity: 1; }
[data-theme='dark'] .dvct__tip:where([data-rk-06b22a]) { background: #fff; color: #000; border-color: rgb(0 0 0 / 0.2); }
[data-theme='dark'] .dvct__tip:where([data-rk-06b22a]) span:last-child:where([data-rk-06b22a]) { color: #333; }
.dvct__live:where([data-rk-06b22a]) { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; }
@media (max-width: 1024px) { .dvct__viewport:where([data-rk-06b22a]) { height: 320px; } }
@media (max-width: 768px) { .dvct__viewport:where([data-rk-06b22a]) { height: 270px; } .dvct__tip:where([data-rk-06b22a]) { font-size: 0.72rem; padding: 0.35rem 0.75rem; } }
@media (max-width: 480px) { .dvct__viewport:where([data-rk-06b22a]) { height: 240px; } }