Component

Mini Map

A canvas/editor overview map — renders items as positioned dots and an optional draggable viewport indicator rectangle. Inspired by IDE minimaps and goal-graph overviews.

Basic overview

Pass an array of world-space items. The minimap auto-fits all of them into its box with uniform scaling.

With viewport

Add a viewport prop to display a semi-transparent indicator rectangle showing the current visible region.

Interactive

Provide onViewportChange to allow clicking or dragging to pan the viewport. The callback receives the new world-space center point.

Viewport: x=50, y=30

Installation

$pnpm add @refraction-ui/react

Usage

tsx

import { MiniMap } from '@refraction-ui/react'
import { useState } from 'react'

const items = [
  { id: 'node-1', x: 0, y: 0, width: 120, height: 80 },
  { id: 'node-2', x: 300, y: 150, width: 100, height: 60 },
]

export function Editor() {
  const [viewport, setViewport] = useState({ x: 0, y: 0, width: 400, height: 300 })

  return (
    <MiniMap
      items={items}
      viewport={viewport}
      onViewportChange={({ x, y }) =>
        setViewport((v) => ({ ...v, x: x - v.width / 2, y: y - v.height / 2 }))
      }
    />
  )
}

Props

Prop	Type	Default	Description
`items`	`MiniMapItem[]`	--	Items to render as dots. Each item has `id`, `x`, `y`, and optional `width`/`height` in world coordinates.
`viewport`	`Rect`	--	Current viewport in world coordinates `{ x, y, width, height }`. When provided, renders a viewport indicator rectangle.
`width`	`number`	`200`	Width of the minimap box in px.
`height`	`number`	`140`	Height of the minimap box in px.
`padding`	`number`	`8`	Inset padding in px applied to all sides before fitting content.
`onViewportChange`	`(center: { x: number; y: number }) => void`	--	If provided, the minimap becomes interactive — click or drag to emit the new world-space center for the viewport.
`className`	`string`	--	Additional CSS classes to apply to the minimap container.