(Footer: total count and Less/More legend)"
],
"physics": {
"engine": "Motion Spring Gliding & popLayout Text Transitions",
"description": "A spring (stiffness 480, damping 32, mass 0.5) moves the tooltip between hovered cells, and popLayout transitions (140ms ease-out) swap the count and date text.",
"parameters": [
{
"label": "Cell Hover Scale",
"value": "1.25 (25% magnification)"
},
{
"label": "Transition Duration",
"value": "150ms cubic-bezier(0.4, 0, 0.2, 1)"
},
{
"label": "Tooltip Delay",
"value": "0ms instantaneous binding"
}
]
},
"accessibility": {
"aria": "No ARIA attributes are set. Cells are unlabelled divs, so counts and dates are only available through the mouse hover tooltip. The root spreads extra props, so you can pass role and aria-label.",
"reducedMotion": "No reduced-motion handling. The cell hover scale and the tooltip spring and text transitions always run.",
"keyboard": [
{
"key": "None",
"description": "No element is focusable. The tooltip opens on mouse hover only."
}
]
},
"guidelines": {
"recommended": [
"Developer portfolio hero sections and about pages",
"Open-source organization dashboards and profile cards",
"Telemetry and commit streak tracking widgets"
],
"bestPractices": [
"Pass real contribution data through data or contributions to replace the generated sample data. The component does not fetch from GitHub.",
"totalContributions is optional. When omitted it is the sum of all cell counts; if you pass it, keep it equal to that sum.",
"With the default blockSize (10) and blockGap (3) a full year is about 690px wide. Narrower containers scroll horizontally, and below a 768px viewport the grid starts scrolled to the latest week."
]
},
"props": [
{
"name": "username",
"type": "string",
"defaultValue": "undefined",
"description": "GitHub username shown as @username under the title when no subtitle is set. No data is fetched."
},
{
"name": "title",
"type": "string",
"defaultValue": "\"Commit Heatmap\"",
"description": "Main header title for the contribution heatmap card."
},
{
"name": "subtitle",
"type": "string",
"defaultValue": "undefined",
"description": "Secondary header label or user attribution."
},
{
"name": "totalContributions",
"type": "number",
"defaultValue": "sum of data",
"description": "Total shown in the footer. Defaults to the sum of the contribution counts."
},
{
"name": "year",
"type": "number",
"defaultValue": "current year",
"description": "Year used for the footer label and for the generated sample data when no data is passed."
},
{
"name": "variant",
"type": "\"teal\" | \"emerald\" | \"github\"",
"defaultValue": "\"teal\"",
"description": "Color theme of the heatmap cells."
},
{
"name": "blockSize",
"type": "number",
"defaultValue": "10",
"description": "Size of each day cell in pixels."
},
{
"name": "blockGap",
"type": "number",
"defaultValue": "3",
"description": "Gap between day cells in pixels."
},
{
"name": "contributions",
"type": "Contribution[]",
"defaultValue": "generated sample year",
"description": "Contribution entries ({ date, count, level }) to render. When empty, a deterministic sample for the full year is generated."
},
{
"name": "data",
"type": "Contribution[]",
"description": "Alias of contributions. Takes precedence when both are set."
},
{
"name": "className",
"type": "string",
"defaultValue": "undefined",
"description": "Additional CSS utility classes applied to the root card wrapper."
},
{
"name": "children",
"type": "ReactNode",
"description": "Custom layout built from the ContributionGraph* subcomponents. Replaces the default header, calendar and footer."
}
],
"usage": "import { GitHubActivity, type Contribution } from \"@/components/ui/github-activity\";\n\nconst data: Contribution[] = [\n { date: \"2026-01-05\", count: 4, level: 2 },\n { date: \"2026-01-06\", count: 9, level: 3 },\n];\n\nexport function GitHubActivityDemo() {\n return
;\n}",
"files": [
{
"name": "github-activity.tsx",
"path": "registry/ui/github-activity.tsx",
"code": "\"use client\";\n\nimport * as React from \"react\";\nimport {\n useState,\n useRef,\n useMemo,\n useEffect,\n createContext,\n useContext,\n} from \"react\";\nimport { motion, AnimatePresence } from \"motion/react\";\nimport { cn } from \"@/lib/utils\";\n\nexport type ContributionLevel = 0 | 1 | 2 | 3 | 4;\n\nexport type Contribution = {\n date: string;\n count: number;\n level: ContributionLevel;\n};\n\nexport type Activity = Contribution;\n\nexport type GitHubActivityVariant = \"emerald\" | \"teal\" | \"github\";\n\nexport interface GitHubActivityProps extends React.HTMLAttributes
{\n username?: string;\n title?: string;\n subtitle?: string;\n totalContributions?: number;\n year?: number;\n contributions?: Contribution[];\n data?: Contribution[];\n variant?: GitHubActivityVariant;\n blockSize?: number;\n blockGap?: number;\n className?: string;\n}\n\nconst MONTH_NAMES = [\n \"Jan\",\n \"Feb\",\n \"Mar\",\n \"Apr\",\n \"May\",\n \"Jun\",\n \"Jul\",\n \"Aug\",\n \"Sep\",\n \"Oct\",\n \"Nov\",\n \"Dec\",\n];\n\nconst VARIANT_CONFIGS: Record<\n GitHubActivityVariant,\n {\n levels: Record;\n badge: string;\n dot: string;\n text: string;\n glow: string;\n }\n> = {\n teal: {\n levels: {\n 0: \"bg-zinc-200/80 border border-zinc-300/60 dark:bg-white/4 dark:border-white/4\",\n 1: \"bg-[#015451]/35 border border-[#015451]/50\",\n 2: \"bg-[#015451]/65 border border-[#00c9a7]/40\",\n 3: \"bg-[#00a88c] border border-[#00c9a7]/70 shadow-[0_0_8px_rgba(0,201,167,0.35)]\",\n 4: \"bg-[#00c9a7] border border-[#5eead4] shadow-[0_0_12px_rgba(0,201,167,0.65)]\",\n },\n badge: \"bg-[#00c9a7]/10 text-[#00c9a7] border border-[#00c9a7]/25\",\n dot: \"bg-[#00c9a7]\",\n text: \"text-[#00c9a7]\",\n glow: \"bg-[#00c9a7]/12\",\n },\n emerald: {\n levels: {\n 0: \"bg-zinc-200/80 border border-zinc-300/60 dark:bg-white/4 dark:border-white/4\",\n 1: \"bg-[#0e4429] border border-[#006d32]/40\",\n 2: \"bg-[#006d32] border border-[#26a641]/50\",\n 3: \"bg-[#26a641] border border-[#39d353]/60 shadow-[0_0_8px_rgba(38,166,65,0.35)]\",\n 4: \"bg-[#39d353] border border-[#4ae365] shadow-[0_0_12px_rgba(57,211,83,0.6)]\",\n },\n badge: \"bg-emerald-500/10 text-emerald-400 border border-emerald-500/20\",\n dot: \"bg-emerald-400\",\n text: \"text-emerald-400\",\n glow: \"bg-emerald-500/12\",\n },\n github: {\n levels: {\n 0: \"bg-zinc-200/80 border border-zinc-300/60 dark:bg-white/4 dark:border-white/4\",\n 1: \"bg-[#0e4429] border border-[#006d32]/40\",\n 2: \"bg-[#006d32] border border-[#26a641]/50\",\n 3: \"bg-[#26a641] border border-[#39d353]/60 shadow-[0_0_8px_rgba(38,166,65,0.35)]\",\n 4: \"bg-[#39d353] border border-[#4ae365] shadow-[0_0_12px_rgba(57,211,83,0.6)]\",\n },\n badge: \"bg-emerald-500/10 text-emerald-400 border border-emerald-500/20\",\n dot: \"bg-emerald-400\",\n text: \"text-emerald-400\",\n glow: \"bg-emerald-500/12\",\n },\n};\n\ntype Week = Array;\n\ntype MonthLabel = {\n weekIndex: number;\n label: string;\n};\n\nfunction generateYearData(targetYear: number): Contribution[] {\n const result: Contribution[] = [];\n const start = new Date(targetYear, 0, 1);\n const end = new Date(targetYear, 11, 31);\n\n const current = new Date(start);\n while (current <= end) {\n const year = current.getFullYear();\n const month = String(current.getMonth() + 1).padStart(2, \"0\");\n const day = String(current.getDate()).padStart(2, \"0\");\n const dateStr = `${year}-${month}-${day}`;\n\n const seed =\n (targetYear * 365 + (current.getMonth() + 1) * 31 + current.getDate()) *\n 17;\n const pseudoRand = ((seed * 9301 + 49297) % 233280) / 233280;\n\n let level: ContributionLevel = 0;\n let count = 0;\n\n if (pseudoRand > 0.82) {\n level = 4;\n count = 13 + Math.floor(pseudoRand * 12);\n } else if (pseudoRand > 0.62) {\n level = 3;\n count = 7 + Math.floor(pseudoRand * 6);\n } else if (pseudoRand > 0.42) {\n level = 2;\n count = 3 + Math.floor(pseudoRand * 4);\n } else if (pseudoRand > 0.22) {\n level = 1;\n count = 1 + Math.floor(pseudoRand * 2);\n }\n\n result.push({\n date: dateStr,\n count,\n level,\n });\n\n current.setDate(current.getDate() + 1);\n }\n\n return result;\n}\n\nfunction parseDateString(dateStr: string): Date {\n const [y, m, d] = dateStr.split(\"-\").map(Number);\n return new Date(y, (m || 1) - 1, d || 1);\n}\n\nfunction formatDateDisplay(dateStr: string): string {\n const date = parseDateString(dateStr);\n const m = MONTH_NAMES[date.getMonth()];\n const d = date.getDate();\n const y = date.getFullYear();\n return `${m} ${d}, ${y}`;\n}\n\nfunction groupIntoWeeks(data: Contribution[], weekStart = 0): Week[] {\n if (!data || data.length === 0) return [];\n\n const sorted = [...data].sort((a, b) => a.date.localeCompare(b.date));\n const firstDate = parseDateString(sorted[0].date);\n const firstDay = firstDate.getDay();\n\n const leadingPadding = (firstDay - weekStart + 7) % 7;\n const padded: Array = [\n ...new Array(leadingPadding).fill(undefined),\n ...sorted,\n ];\n\n const weeksCount = Math.ceil(padded.length / 7);\n const weeks: Week[] = [];\n\n for (let w = 0; w < weeksCount; w++) {\n const weekSlice = padded.slice(w * 7, w * 7 + 7);\n while (weekSlice.length < 7) {\n weekSlice.push(undefined);\n }\n weeks.push(weekSlice);\n }\n\n return weeks;\n}\n\nfunction calculateMonthLabels(weeks: Week[]): MonthLabel[] {\n const labels: MonthLabel[] = [];\n\n weeks.forEach((week, weekIndex) => {\n const validDay = week.find((day) => day !== undefined);\n if (!validDay) return;\n\n const date = parseDateString(validDay.date);\n const month = MONTH_NAMES[date.getMonth()];\n const prev = labels[labels.length - 1];\n\n if (weekIndex === 0 || !prev || prev.label !== month) {\n labels.push({ weekIndex, label: month });\n }\n });\n\n return labels.filter(({ weekIndex }, index) => {\n const minWeeks = 2;\n if (index === 0) {\n return labels[1] ? labels[1].weekIndex - weekIndex >= minWeeks : true;\n }\n if (index === labels.length - 1) {\n return weeks.length - weekIndex >= minWeeks;\n }\n return true;\n });\n}\n\ntype ContributionGraphContextType = {\n data: Contribution[];\n weeks: Week[];\n monthLabels: MonthLabel[];\n blockSize: number;\n blockGap: number;\n totalContributions: number;\n year: number;\n variant: GitHubActivityVariant;\n activeTheme: (typeof VARIANT_CONFIGS)[\"teal\"];\n hoveredCell: {\n count: number;\n date: string;\n x: number;\n y: number;\n height: number;\n isNearTop: boolean;\n } | null;\n setHoveredCell: React.Dispatch<\n React.SetStateAction<{\n count: number;\n date: string;\n x: number;\n y: number;\n height: number;\n isNearTop: boolean;\n } | null>\n >;\n containerRef: React.RefObject;\n scrollRef: React.RefObject;\n};\n\nconst ContributionGraphContext =\n createContext(null);\n\nexport function useContributionGraph() {\n const context = useContext(ContributionGraphContext);\n if (!context) {\n throw new Error(\n \"ContributionGraph components must be used within a ContributionGraph provider\",\n );\n }\n return context;\n}\n\nexport function ContributionGraph({\n username,\n title = \"Commit Heatmap\",\n subtitle,\n totalContributions: totalContributionsProp,\n year = new Date().getFullYear(),\n contributions,\n data: dataProp,\n variant = \"teal\",\n blockSize = 10,\n blockGap = 3,\n className,\n children,\n ...props\n}: GitHubActivityProps & { children?: React.ReactNode }) {\n const containerRef = useRef(null);\n const scrollRef = useRef(null);\n\n const [hoveredCell, setHoveredCell] = useState<{\n count: number;\n date: string;\n x: number;\n y: number;\n height: number;\n isNearTop: boolean;\n } | null>(null);\n\n const rawData = dataProp || contributions;\n const data = useMemo(() => {\n if (rawData && rawData.length > 0) {\n return rawData;\n }\n return generateYearData(year);\n }, [rawData, year]);\n\n const weeks = useMemo(() => groupIntoWeeks(data, 0), [data]);\n const monthLabels = useMemo(() => calculateMonthLabels(weeks), [weeks]);\n\n const calculatedTotal = useMemo(\n () => data.reduce((sum, item) => sum + item.count, 0),\n [data],\n );\n\n const totalContributions =\n typeof totalContributionsProp === \"number\"\n ? totalContributionsProp\n : calculatedTotal;\n\n const activeTheme = VARIANT_CONFIGS[variant] || VARIANT_CONFIGS.teal;\n\n useEffect(() => {\n if (scrollRef.current && typeof window !== \"undefined\") {\n if (window.innerWidth < 768) {\n scrollRef.current.scrollLeft = scrollRef.current.scrollWidth;\n }\n }\n }, [weeks.length]);\n\n return (\n \n \n {children || (\n <>\n \n \n {title}\n \n \n {subtitle ||\n (username ? `@${username}` : \"GitHub Contribution Matrix\")}\n \n
\n\n \n\n \n\n \n \n \n \n \n )}\n