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