@jeevandev/flow-canvas

A powerful, production-ready, page-based canvas editor library for React. Build interactive design experiences like Figma/Canva with drag, resize, rotate, grouping, and multi-page support.

✨ Features

• 🎨 Multi-Page Canvas - Create and manage multiple pages with smooth scrolling

• 🖱️ Interactive Elements - Drag, resize, rotate with smooth interactions

• 📏 Smart Snapping & Margins - Visual snap guides and customizable page margins

• 🔄 Cross-Page Dragging - Move elements between pages with ghost preview

• 👥 Grouping - Group/ungroup elements with professional editing mode

• 🎯 Multi-Selection - Select and manipulate multiple elements

• ⌨️ Keyboard Shortcuts - Full keyboard support (Undo/Redo, Copy/Paste, etc.)

• 🔍 Zoom & Pan - Smooth zoom controls

• ⚡ High Performance - Viewport culling and virtualization for large datasets

• ♿ Accessible - ARIA labels and keyboard navigation support

• 📦 TypeScript - Full type safety and IntelliSense support

• 🎨 Customizable - Extensive configuration options and theming

📦 Installation

npm install @jeevandev/flow-canvas

🚀 Quick Start

import { Editor, Canvas } from "@jeevandev/flow-canvas";
import "@jeevandev/flow-canvas/style.css";

function App() {
  const initialPages = [
    {
      id: "page-1",
      width: 1920,
      height: 1080,
      name: "Page 1",
      backgroundColor: "#ffffff",
    },
  ];

  return (
    <Editor
      initialPages={initialPages}
      config={{
        snapping: true,
        snapGuide: true,
        showGrid: true,
        gridSize: 20,
      }}
    >
      <Canvas />
    </Editor>
  );
}

📖 Documentation

Complete documentation is available in the docs/ directory:

• Getting Started - Installation and basic usage
• API Reference - Complete API documentation
• Configuration - Configuration options
• Advanced Usage - Advanced features and customization
• Architecture - Architecture overview
• Examples - Code examples and recipes

See docs/README.md for the complete documentation index.

🎯 Core Concepts

Pages

Pages are the containers for your design elements. Each page has dimensions, background color, and can contain multiple elements.

const pages = [
  {
    id: "page-1",
    width: 1920,
    height: 1080,
    backgroundColor: "#ffffff",
    name: "Home Page",
  },
];

Nodes (Elements)

Nodes are the interactive elements on your canvas. They can be dragged, resized, rotated, and grouped.

const nodes = [
  {
    id: "node-1",
    x: 100,
    y: 100,
    width: 200,
    height: 100,
    pageId: "page-1",
    draggable: true,
    resizable: true,
    rotatable: true,
    data: { label: "My Element" },
  },
];

Configuration

Customize the editor behavior with the config prop:

<Editor
  config={{
    snapping: true,        // Enable snapping
    snapGuide: true,        // Show snap guides
    showGrid: true,         // Show grid
    gridSize: 20,          // Grid size in pixels
    pageWidth: 1920,       // Default page width
    pageHeight: 1080,      // Default page height
    minZoom: 0.1,          // Minimum zoom level
    maxZoom: 3,            // Maximum zoom level
    rotation: true,         // Enable rotation
    viewportCulling: true, // Enable viewport culling
  }}
>

🔧 Basic Usage

Adding Elements

import { useEditor } from "@jeevandev/flow-canvas";

function Toolbar() {
  const addNode = useEditor((state) => state.addNode);

  const handleAddElement = () => {
    addNode({
      id: `element-${Date.now()}`,
      x: 100,
      y: 100,
      width: 200,
      height: 100,
      pageId: "page-1",
      draggable: true,
      resizable: true,
      rotatable: true,
    });
  };

  return <button onClick={handleAddElement}>Add Element</button>;
}

Custom Node Types

import { NodeComponentProps } from "@jeevandev/flow-canvas";

const CustomNode = ({ data, style, className }: NodeComponentProps) => (
  <div style={style} className={className}>
    <h2>{data?.title}</h2>
    <p>{data?.description}</p>
  </div>
);

<Canvas nodeTypes={{ custom: CustomNode }} />;

Selection

const selectedIds = useEditor((state) => state.selectedIds);
const selectNode = useEditor((state) => state.selectNode);
const deselectAll = useEditor((state) => state.deselectAll);

// Select a node
selectNode("node-1");

// Deselect all
deselectAll();

🎨 Styling

The library includes default styles that you can import:

import "@jeevandev/flow-canvas/style.css";

You can customize styles using CSS variables or by overriding the default classes. See Configuration for details.

⚡ Performance

The library is optimized for performance:

• Viewport Culling - Only renders visible elements (enabled by default)
• Virtualization - Advanced virtualization for 100+ elements
• Memoization - React.memo and useMemo for optimal re-renders
• Bundle Size - Optimized bundle (121KB UMD, 38KB gzipped)

📊 Bundle Size

| Format | Size | Gzipped | | --------- | ------ | ------- | | ES Module | 165 KB | 43 KB | | UMD | 121 KB | 38 KB | | CSS | 13 KB | 2.8 KB |

🧪 Development

# Install dependencies
npm install

# Start dev server
npm run dev

# Build library
npm run build

# Run tests
npm test

# Type check
npx tsc --noEmit

📝 Changelog

See CHANGELOG.md for version history and release notes.

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines and code of conduct.

📄 License

MIT © Jeevan Jose

🙏 Acknowledgments

Built with:

• React
• Zustand - State management
• @use-gesture/react - Gesture handling
• Vite - Build tool

Ready for production use ✅ | TypeScript ✅ | Accessible ✅ | Well-tested ✅