Website · Documentation · GitHub · Changelog

Overview

@bpmnkit/canvas renders BPMN 2.0 diagrams as interactive SVG. It has zero runtime dependencies, works in any framework (or none), and exposes a plugin API for extending its behaviour.

Features

• SVG rendering — crisp diagrams at any zoom level, all element types
• Pan & zoom — mouse drag, scroll wheel, touch/pinch, keyboard shortcuts
• Theming — light / dark / system-auto, fully overridable via CSS custom properties
• Plugin API — install composable CanvasPlugin add-ons without touching core code
• Event system — subscribe to element clicks, selection changes, diagram load, viewport updates
• Keyboard navigation — arrow keys, fit-to-screen, zoom shortcuts
• Zero dependencies — runs in browsers, bundlers, and SSR

Installation

npm install @bpmnkit/canvas

Quick Start

import { BpmnCanvas } from "@bpmnkit/canvas"

const canvas = new BpmnCanvas({
  container: document.getElementById("canvas")!,
  theme: "dark",          // "light" | "dark" | "auto"
  grid: true,             // dot-grid background
  plugins: [],            // CanvasPlugin[]
})

// Load a diagram
canvas.loadXML(bpmnXml)

// Respond to element clicks
canvas.on("element:click", (id, event) => {
  console.log("Clicked:", id)
})

// Fit diagram to container
canvas.fit()

API Reference

Constructor Options

interface CanvasOptions {
  container: HTMLElement
  theme?: "light" | "dark" | "auto"   // default: "auto"
  grid?: boolean                       // default: false
  fit?: boolean                        // auto-fit on load, default: true
  plugins?: CanvasPlugin[]
}

CanvasApi Methods

| Method | Description | |--------|-------------| | loadXML(xml) | Parse and render a BPMN XML string | | fit() | Fit the diagram to the container | | zoom(factor) | Set zoom level (1 = 100%) | | getShapes() | All rendered RenderedShape objects | | getEdges() | All rendered RenderedEdge objects | | setTheme(theme) | Switch theme at runtime | | destroy() | Remove canvas and clean up | | on(event, handler) | Subscribe to a canvas event | | off(event, handler) | Unsubscribe |

Events

| Event | Payload | Description | |-------|---------|-------------| | diagram:load | BpmnDefinitions | Fired when a new diagram loads | | element:click | (id, PointerEvent) | An element was clicked | | editor:select | string[] | Selection changed (element IDs) | | viewport:change | ViewportState | Pan or zoom occurred |

Plugin API

import type { CanvasPlugin, CanvasApi } from "@bpmnkit/canvas"

const myPlugin: CanvasPlugin = {
  name: "my-plugin",
  install(api: CanvasApi) {
    api.on("element:click", (id) => console.log("clicked", id))
  },
  uninstall() {},
}

Related Packages

| Package | Description | |---------|-------------| | @bpmnkit/core | BPMN/DMN/Form parser, builder, layout engine | | @bpmnkit/editor | Full-featured interactive BPMN editor | | @bpmnkit/engine | Lightweight BPMN process execution engine | | @bpmnkit/feel | FEEL expression language parser & evaluator | | @bpmnkit/plugins | 22 composable canvas plugins | | @bpmnkit/api | Camunda 8 REST API TypeScript client | | @bpmnkit/ascii | Render BPMN diagrams as Unicode ASCII art | | @bpmnkit/ui | Shared design tokens and UI components | | @bpmnkit/profiles | Shared auth, profile storage, and client factories for CLI & proxy | | @bpmnkit/operate | Monitoring & operations frontend for Camunda clusters | | @bpmnkit/connector-gen | Generate connector templates from OpenAPI specs | | @bpmnkit/cli | Camunda 8 command-line interface (casen) | | @bpmnkit/proxy | Local AI bridge and Camunda API proxy server | | @bpmnkit/cli-sdk | Plugin authoring SDK for the casen CLI | | @bpmnkit/create-casen-plugin | Scaffold a new casen CLI plugin in seconds | | @bpmnkit/casen-report | HTML reports from Camunda 8 incident and SLA data | | @bpmnkit/casen-worker-http | Example HTTP worker plugin — completes jobs with live JSONPlaceholder API data | | @bpmnkit/casen-worker-ai | AI task worker — classify, summarize, extract, and decide using Claude |

License

MIT © BPMN Kit — made by u11g