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; } }