react-matrix-canvas

react-matrix-canvas

A React component library for creating interactive matrix/grid canvases with draggable markers. Perfect for building Eisenhower matrices, BCG matrices, risk matrices, and other quadrant-based UIs.

Features

• 🎯 Flexible Grid System - Support for 2x2, 3x3, or custom grid configurations
• 🖱️ Drag & Drop - Smooth dragging with area detection
• 📱 Touch Support - Full touch device support for mobile
• 💬 Tooltips - Built-in tooltip support with customizable content
• ⌨️ Keyboard Navigation - Full keyboard accessibility
• 🎨 Customizable - Minimal styling, easy to customize
• 📦 Zero Dependencies - Only React as peer dependency
• 🔷 TypeScript - Full type definitions included

Installation

npm install react-matrix-canvas

Quick Start

import { MatrixCanvas, Marker, type AreaConfig } from 'react-matrix-canvas';

const areas: AreaConfig[] = [
  { id: 'urgent-important', label: 'Do First', backgroundColor: '#fee2e2', position: { row: 0, col: 0 } },
  { id: 'not-urgent-important', label: 'Schedule', backgroundColor: '#dbeafe', position: { row: 0, col: 1 } },
  { id: 'urgent-not-important', label: 'Delegate', backgroundColor: '#fef3c7', position: { row: 1, col: 0 } },
  { id: 'not-urgent-not-important', label: 'Eliminate', backgroundColor: '#f3e8ff', position: { row: 1, col: 1 } },
];

function App() {
  const [items, setItems] = useState([
    { id: '1', title: 'Task 1', areaId: 'urgent-important', position: { x: 25, y: 25 } },
  ]);

  return (
    <MatrixCanvas
      areas={areas}
      grid={{ rows: 2, cols: 2 }}
      onCanvasClick={(position, areaId) => {
        // Add new item at clicked position
      }}
      style={{ height: '500px' }}
    >
      {items.map(item => (
        <Marker
          key={item.id}
          id={item.id}
          position={item.position}
          areaId={item.areaId}
          onPositionChange={(newPos) => {
            setItems(prev => prev.map(i =>
              i.id === item.id ? { ...i, position: newPos } : i
            ));
          }}
          onAreaChange={(newArea) => {
            setItems(prev => prev.map(i =>
              i.id === item.id ? { ...i, areaId: newArea } : i
            ));
          }}
          tooltip={<div>{item.title}</div>}
        />
      ))}
    </MatrixCanvas>
  );
}

API Reference

MatrixCanvas

Main container component.

Prop	Type	Description
areas	AreaConfig[]	Area configurations (optional for free canvas)
grid	{ rows: number; cols: number }	Grid dimensions (auto-calculated from areas if omitted)
onCanvasClick	(position, areaId) => void	Callback when clicking empty canvas area
dragEndClickDelay	number	Delay (ms) to ignore clicks after drag ends
renderArea	(area) => ReactNode	Custom area renderer
className	string	Custom class name
style	CSSProperties	Custom styles

Marker

Draggable marker component.

Prop	Type	Description
id	string	Unique identifier
position	{ x: number; y: number }	Position in percentage (0-100)
areaId	string	Current area ID
data	T	Custom data passed to renderTooltip
onPositionChange	(position) => void	Callback when position changes
onAreaChange	(newArea, oldArea) => void	Callback when area changes
onDragEnd	() => void	Callback when drag ends
onClick	() => void	Callback when clicked
tooltip	ReactNode | (data) => ReactNode	Tooltip content
renderTooltip	(props) => ReactNode	Custom tooltip renderer
size	number	Marker size in pixels (default: 20)
color	string	Marker color (default: #3b82f6)
hoverScale	number	Scale on hover (e.g., 1.25)
hoverClassName	string	Class name applied on hover
hoverStyle	CSSProperties	Style applied on hover
disabled	boolean	Disable dragging
className	string	Custom class name
style	CSSProperties	Custom styles

AreaConfig

interface AreaConfig {
  id: string;
  label?: string;
  backgroundColor?: string;
  labelColor?: string;
  position: { row: number; col: number };
}

Examples

Custom Tooltip with renderTooltip

renderTooltipを使うと、ライブラリが提供する位置情報とマウスイベントを使って、独自のツールチップUIを実装できます。

// ライブラリが提供するprops:
// - data: Markerに渡したカスタムデータ
// - position: ツールチップの表示位置 { top, left }
// - onMouseEnter/onMouseLeave: ホバー状態管理用

<Marker
  id="task-1"
  position={{ x: 50, y: 50 }}
  areaId="design"
  data={{ title: 'Task 1', status: 'active' }}
  renderTooltip={({ data, position, onMouseEnter, onMouseLeave }) => (
    <MyCustomTooltip
      title={data.title}
      status={data.status}
      style={{ top: position.top, left: position.left }}
      onMouseEnter={onMouseEnter}
      onMouseLeave={onMouseLeave}
    />
  )}
/>

Real-World Example: Hobbit Matrix

実際のアプリケーションでの使用例（アイゼンハワーマトリクス風のタスク管理）:

import { MatrixCanvas, Marker, type AreaConfig } from 'react-matrix-canvas';
import { createPortal } from 'react-dom';

// エリア設定
const AREA_CONFIGS: AreaConfig[] = [
  { id: 'design', label: 'Design', backgroundColor: '#dbeafe', position: { row: 0, col: 0 } },
  { id: 'action', label: 'Action', backgroundColor: '#dcfce7', position: { row: 0, col: 1 } },
  { id: 'hold', label: 'Hold', backgroundColor: '#fef3c7', position: { row: 1, col: 0 } },
  { id: 'leave', label: 'Leave', backgroundColor: '#fee2e2', position: { row: 1, col: 1 } },
];

// カスタムツールチップ（Portalで表示）
function TaskTooltip({ task, position, onMouseEnter, onMouseLeave, onEdit, onDelete }) {
  return createPortal(
    <div
      className="fixed z-50 rounded-lg bg-white p-3 shadow-xl"
      style={{ top: position.top - 8, left: position.left, transform: 'translate(-50%, -100%)' }}
      onMouseEnter={onMouseEnter}
      onMouseLeave={onMouseLeave}
    >
      <h4>{task.title}</h4>
      <div className="mt-2 flex gap-2">
        <button onClick={onEdit}>編集</button>
        <button onClick={onDelete}>削除</button>
      </div>
    </div>,
    document.body
  );
}

function TaskMatrix({ tasks, onUpdateTask, onDeleteTask }) {
  // カスタムエリアレンダリング
  const renderArea = useCallback((area: AreaConfig) => (
    <div
      className="relative p-4"
      style={{ backgroundColor: area.backgroundColor }}
    >
      <span className="rounded-full bg-white px-3 py-1 shadow">
        {area.label}
      </span>
    </div>
  ), []);

  return (
    <MatrixCanvas
      areas={AREA_CONFIGS}
      grid={{ rows: 2, cols: 2 }}
      onCanvasClick={(position, areaId) => {
        // クリック位置とエリアIDを使って新規タスク作成
        console.log('Clicked at', position, 'in area', areaId);
      }}
      dragEndClickDelay={150}
      renderArea={renderArea}
      className="h-[600px] w-full"
    >
      {tasks.map(task => (
        <Marker
          key={task.id}
          id={task.id}
          position={task.position}
          areaId={task.areaId}
          data={task}
          onPositionChange={(pos) => onUpdateTask(task.id, { position: pos })}
          onAreaChange={(newAreaId) => onUpdateTask(task.id, { areaId: newAreaId })}
          color="#3b82f6"
          size={20}
          hoverScale={1.25}
          renderTooltip={({ data, position, onMouseEnter, onMouseLeave }) => (
            <TaskTooltip
              task={data}
              position={position}
              onMouseEnter={onMouseEnter}
              onMouseLeave={onMouseLeave}
              onEdit={() => console.log('Edit', data.id)}
              onDelete={() => onDeleteTask(data.id)}
            />
          )}
        />
      ))}
    </MatrixCanvas>
  );
}

Hover Effects

<Marker
  id="1"
  position={{ x: 50, y: 50 }}
  hoverScale={1.25}
  hoverClassName="shadow-lg"
  hoverStyle={{ boxShadow: '0 4px 12px rgba(0,0,0,0.3)' }}
/>

Prevent Click After Drag

<MatrixCanvas
  areas={areas}
  dragEndClickDelay={150}  // Ignore clicks for 150ms after drag ends
  onCanvasClick={(position, areaId) => {
    // This won't fire immediately after dragging
  }}
>
  {/* markers */}
</MatrixCanvas>

Free Canvas (No Areas)

<MatrixCanvas>
  <Marker id="1" position={{ x: 50, y: 50 }} />
</MatrixCanvas>

2-Area Layout (Left/Right)

<MatrixCanvas
  areas={[
    { id: 'low', label: 'Low', position: { row: 0, col: 0 } },
    { id: 'high', label: 'High', position: { row: 0, col: 1 } },
  ]}
  grid={{ rows: 1, cols: 2 }}
>
  {/* markers */}
</MatrixCanvas>

3x3 Grid

<MatrixCanvas
  areas={[
    { id: '0-0', position: { row: 0, col: 0 } },
    { id: '0-1', position: { row: 0, col: 1 } },
    { id: '0-2', position: { row: 0, col: 2 } },
    // ... 9 areas total
  ]}
  grid={{ rows: 3, cols: 3 }}
>
  {/* markers */}
</MatrixCanvas>

Architecture

このライブラリは「ライブラリが処理を担当し、アプリがUIを担当する」という設計思想に基づいています。

ライブラリが提供するもの

• ドラッグ＆ドロップの処理
• エリア検出（どのエリアにいるか）
• 位置計算（パーセンテージベース）
• ツールチップの表示位置計算
• マウスイベントのハンドリング

アプリが決めるもの

• エリアの見た目（renderArea）
• ツールチップの見た目（renderTooltip）
• マーカーのスタイル（color, size, classNameなど）
• データの管理と永続化

License

Copyright (c) 2025 yuitonn