mathlean-canvas

mathlean-canvas is a reusable React whiteboard canvas for math-heavy notes, diagrams, matrices, tables, graphs, and geometric constructions.

It is built as a single MathCanvas component. The component includes its own toolbar, drawing surface, object overlays, undo/redo history, light/dark themes, and state callback for saving canvas data.

Features

• Pen and eraser drawing
• Text boxes with plain text, LaTeX rendering, inline math, formatting, colors, resizing, copy, and delete actions
• Graph nodes and directed relationships with fast keyboard creation and navigation
• Matrices with LaTeX export, grid selection, separators, region transforms, rotation, transpose, and identity fill
• Tables with spreadsheet-like editing, range selection, row/column operations, and copy/paste
• Geometry construction tools for points, segments, polygons, angles, circles, labels, midpoints, helpers, fixed lengths, regular polygons, right-angle markers, and equal-side markers
• Square grid and coordinate plane backgrounds
• Undo/redo and clear canvas controls
• Controlled persistence through initialState and onStateChange

For the full user-facing tool guide and shortcut reference, see features.md.

Install

npm install mathlean-canvas

The package is built for React apps and uses:

• react
• react-dom
• react-konva
• konva
• katex
• mathlive

The current package version is built and tested with React 19, React DOM 19, React Konva 19, Konva 10, KaTeX 0.16, and MathLive 0.109.

If your app uses React 18 or older, check compatibility carefully. The safest setup is a React 19 app with the matching Konva/React Konva stack.

Basic Usage

import { MathCanvas } from "mathlean-canvas";

export default function App() {
  return (
    <div style={{ width: "100vw", height: "100vh" }}>
      <MathCanvas />
    </div>
  );
}

MathCanvas fills its parent container, so give the parent an explicit width and height.

Styles

The source imports KaTeX and MathLive styles for the built-in math editors. If your bundler does not include package CSS automatically, import the math styles in your app entry:

import "katex/dist/katex.min.css";
import "mathlive/fonts.css";
import "mathlive/static.css";

Saving And Restoring State

Use onStateChange to receive the full canvas state whenever it changes, then pass that state back through initialState when you want to restore the canvas.

import { useState } from "react";
import { MathCanvas, type CanvasState } from "mathlean-canvas";

export default function NotesCanvas() {
  const [savedState, setSavedState] = useState<CanvasState | undefined>();

  return (
    <div style={{ width: "100%", height: 600 }}>
      <MathCanvas
        initialState={savedState}
        onStateChange={setSavedState}
      />
    </div>
  );
}

initialState is read when the component initializes. If you need to switch between multiple documents at runtime, remount the component with a different key.

<MathCanvas
  key={documentId}
  initialState={document.canvasState}
  onStateChange={saveCanvasState}
/>

Dark Mode

<MathCanvas darkMode />

The component ships with built-in light and dark themes. Use className and style for layout-level styling around the canvas.

API

type MathCanvasProps = {
  darkMode?: boolean;
  className?: string;
  style?: React.CSSProperties;
  initialState?: CanvasState;
  onStateChange?: (state: CanvasState) => void;
};

Exports:

export { MathCanvas };
export default MathCanvas;
export type { CanvasState, MathCanvasProps };

Tools At A Glance

• Select: select, move, resize, and edit existing objects.
• Pan: drag the viewport.
• Pen: draw freehand strokes.
• Eraser: erase freehand strokes.
• Text: place text boxes and math text.
• Graph: create nodes and connect relationships.
• Matrix: create and edit matrices.
• Table: create and edit tables.
• Geometry: construct mathematical diagrams.
• Toggle LaTeX: switch text entry between plain and LaTeX-oriented rendering.
• Clear: clear the canvas.

See features.md for detailed tutorials and shortcuts.

Project Structure

src/
  MathCanvas.tsx              canvas coordinator
  MathCanvas/
    core/                     canvas-wide hooks
    features/
      text/                   text boxes and inline math
      graph/                  graph nodes and edges
      grid/                   matrices and tables
      geometry/               geometry construction tools
      stroke/                 pen and eraser strokes
    components/               shared toolbar, overlays, icons
    types.ts                  public and internal canvas state types
  index.ts                    package entry
demo/                         local Vite demo app
docs/                         architecture and planning notes
tests/                        Playwright tests

For contributor-facing architecture notes, see docs/mathcanvas-architecture.md.

Local Development

Install dependencies:

npm install

Run the demo app:

npm run dev

Build the library package:

npm run build

Build the demo app:

npm run build:demo

Run lint:

npm run lint

Run Playwright tests:

npm run test:e2e

Focused test scripts are also available for MathLive/textbox behavior:

npm run test:e2e:placeholders
npm run test:e2e:exit
npm run test:e2e:mathlive

License

MIT