activity terrain.md
Activity Terrain
A contribution heatmap that tilts up into a 3D terrain you can turn, built with React and canvas.
Source: https://kokonutui.com/docs/cards/activity-terrain
Installation
npx shadcn@latest add @kokonutui/activity-terrain
Props
| Prop | Type | Default | Description |
|---|---|---|---|
data? |
number[] |
built-in |
Count per day, oldest first. |
endDate? |
string |
"2026-10-11" |
The day of the last value, as YYYY-MM-DD. |
title? |
string |
"Activity" |
|
defaultFlat? |
boolean |
false |
Start in the flat, heatmap view. |
className? |
string |
Extra classes for the root element. |
Source
"use client";
/**
* @author: @dorianbaffier
* @description: Activity Terrain
* @version: 1.0.0
* @date: 2026-10-14
* @license: MIT
* @website: https://kokonutui.com
* @github: https://github.com/kokonut-labs/kokonutui
*/
import {
type KeyboardEvent,
type PointerEvent,
useCallback,
useEffect,
useMemo,
useRef,
useState,
} from "react";
import { cn } from "@/lib/utils";
// Constants and functions defined here...
export default function ActivityTerrain({
data = DEFAULT_DATA,
endDate = "2026-10-11",
title = "Activity",
defaultFlat = false,
className,
}: ActivityTerrainProps) {
const cells = useMemo(() => buildCells(data, endDate), [data, endDate]);
const weeks = (cells.at(-1)?.col ?? 0) + 1;
const total = useMemo(() => data.reduce((sum, n) => sum + n, 0), [data]);
const [flat, setFlat] = useState(defaultFlat);
const [active, setActive] = useState<Cell | null>(null);
const [dragging, setDragging] = useState(false);
const canvasRef = useRef<HTMLCanvasElement>(null);
const paletteRef = useRef<Palette | null>(null);
const sim = useRef({
yaw: 0,
yawSpeed: 0,
pitch: 0,
pitchSpeed: 0,
pitchTarget: defaultFlat ? 0 : PITCH_TERRAIN,
bumps: new Float64Array(cells.length),
bumpSpeeds: new Float64Array(cells.length),
hovered: -1,
origin: { col: 0, row: 3 },
width: 0,
height: 0,
dpr: 1,
drag: null as null | {
id: number;
x: number;
y: number;
yaw: number;
pitch: number;
moved: boolean;
samples: { t: number; x: number; y: number }[];
},
raf: 0,
last: 0,
visible: false,
started: false,
reduceMotion: false,
});
const cellsRef = useRef(cells);
// additional component logic and event handlers...
return (
<div
className={cn(
"w-full max-w-2xl select-none rounded-3xl border border-zinc-200 bg-white text-zinc-900 dark:border-zinc-800 dark:bg-zinc-950 dark:text-zinc-100",
className
)}
>
<canvas
aria-label={`${title}: ${total.toLocaleString("en-US")} contributions over ${weeks} weeks. Use the arrow keys to read each day.`}
className={cn(
"block h-72 w-full touch-pan-y rounded-b-3xl outline-none focus-visible:ring-2 focus-visible:ring-zinc-400 focus-visible:ring-inset",
dragging ? "cursor-grabbing" : "cursor-grab"
)}
ref={canvasRef}
/>
{/* Additional elements like labels and information */}
</div>
);
}