Blocks / Minimap

Minimap

A miniature of the world with the viewport as a rectangle: drag to pan, click to jump, corner to zoom, arrows for the keyboard.

import { Minimap, editorMinimapFit, editorToMap, editorFromMap, editorPanViewport, editorScaleViewport, editorBoundsOf } from "@forgeron/ui";
/01 → Default
X 200 · Y 100 · W 640 · ARROWS PAN, + − ZOOM
import { Minimap, type EditorRect } from "@forgeron/ui";
import { useState } from "react";

const items = [
  { id: "a", x: 0, y: 0, w: 600, h: 400 },
  { id: "b", x: 700, y: 120, w: 500, h: 300, tone: "accent" as const },
  { id: "c", x: 300, y: 560, w: 700, h: 360 },
  { id: "d", x: 1300, y: 600, w: 300, h: 300, tone: "muted" as const },
];

export default function Default() {
  const [viewport, setViewport] = useState<EditorRect>({ x: 200, y: 100, w: 640, h: 400 });
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12, alignItems: "flex-start" }}>
      <Minimap
        label="Canvas overview"
        items={items}
        viewport={viewport}
        onViewportChange={setViewport}
      />
      <span style={{ font: "400 12px var(--font-mono)", color: "var(--ink-muted)" }}>
        X {Math.round(viewport.x)} · Y {Math.round(viewport.y)} · W {Math.round(viewport.w)} ·
        ARROWS PAN, + − ZOOM
      </span>
    </div>
  );
}
/02 → With canvas
Brief
Moodboard
Flow
Notes
import { Minimap, type EditorRect } from "@forgeron/ui";
import { useState } from "react";

const items = [
  { id: "a", x: 0, y: 0, w: 600, h: 400, label: "Brief" },
  { id: "b", x: 700, y: 120, w: 500, h: 300, label: "Moodboard" },
  { id: "c", x: 300, y: 560, w: 700, h: 360, label: "Flow" },
  { id: "d", x: 1300, y: 600, w: 300, h: 300, label: "Notes" },
];
const SCREEN = { w: 360, h: 240 };

export default function WithCanvas() {
  const [viewport, setViewport] = useState<EditorRect>({ x: 100, y: 60, w: 720, h: 480 });
  const zoom = SCREEN.w / viewport.w;
  return (
    <div style={{ display: "flex", flexWrap: "wrap", gap: 16, alignItems: "flex-start" }}>
      <div
        role="img"
        aria-label="Canvas, as seen through the minimap's rectangle"
        style={{
          position: "relative",
          width: SCREEN.w,
          height: SCREEN.h,
          overflow: "hidden",
          border: "1px solid var(--line-strong)",
          background: "var(--bg-sunk)",
        }}
      >
        {items.map((it) => (
          <div
            key={it.id}
            style={{
              position: "absolute",
              left: (it.x - viewport.x) * zoom,
              top: (it.y - viewport.y) * zoom,
              width: it.w * zoom,
              height: it.h * zoom,
              border: "1px solid var(--ink-dim)",
              background: "var(--bg-raised)",
              padding: 4,
              font: "400 11px var(--font-mono)",
              color: "var(--ink-muted)",
              textTransform: "uppercase",
            }}
          >
            {it.label}
          </div>
        ))}
      </div>
      <Minimap
        label="Canvas overview"
        items={items}
        viewport={viewport}
        onViewportChange={setViewport}
        width={220}
        height={160}
      />
    </div>
  );
}
API → Props
PropTypeDefaultDescription
labelstring—Names the map: “Canvas overview”.
items{ id, x, y, w, h, tone? }[]—Drawn as plain rectangles, in world units. tone: default, accent or muted.
world{ x, y, w, h }—The area shown. Default: the items' bounds with a margin.
viewport{ x, y, w, h }—What is on screen, in world units.
onViewportChange / onViewportCommit(viewport) => void—While dragging, resizing or pressing keys; and when it ends. Without onViewportChange the map only shows.
width / heightnumber200 / 140The map in px.
resizablebooleantrueA corner handle, and + / − keys, scale the viewport around its centre.
limits{ minW, maxW }—How wide the viewport can get, in world units.
stepnumber—World units per arrow press (Shift: five times). Default a tenth of the viewport.
classNamestring—Extra classes.