LeaferJS leafer-ui: A Canvas Engine Built for Large Scene Graphs

What leafer-ui Solves, and Who It Is Aimed At

Canvas gives you a bitmap and an API for drawing shapes onto it. It does not give you a scene tree, hit testing, layout, or an editing model. Every team that builds a design tool or a whiteboard ends up writing those things, and the writing is where the schedule goes. leafer-ui is the UI layer of an engine that ships them instead. The repository README frames the target directly: it describes the project as a Canvas engine that can run a million graphics in the browser and as a Canvas core capable of a Figma-class editor.

The intended audience is narrow and specific. The README lists AI infinite canvases, AI design tools, graphic editors, online design platforms in the Figma and Canva category, whiteboards, low-code engines, industrial topology and monitoring diagrams, batch image and poster generation, and interactive H5. What those have in common is a scene graph that users manipulate: elements are selected, dragged, resized, and reordered. If your output is a static chart or a one-shot illustration, the scene graph is overhead you are paying for and not using.

The repository is split rather than monolithic. leafer-ui is the UI presentation layer, sitting on top of leafer (the engine core), with leafer-in for official plugins, leafer-x for community plugins, and separate repositories for tests, examples, and documentation. That split matters when you install, which the next sections cover.

Scene Tree, Hit Testing, and the DOM Analogy

The design choice that shapes everything else is the DOM-like API. You construct a Leafer instance bound to a view, construct shapes as objects, and add them to the tree. Attributes are set as properties on the object, not through imperative draw calls. The README describes the structured scene tree as the mechanism that lets an AI operate graphics the way it operates a DOM, which is the stated reason the project calls itself an infinite canvas engine for the AI era.

Above the tree sit the features a plain Canvas wrapper does not have. Hit testing is described as millisecond-level, which is what makes drag, zoom, and multi-touch work without you writing spatial indexing. Flex layout is implemented natively inside the engine, a combination the README calls rare among Canvas engines. The Editor plugin adds scaling, rotation, movement, and multi-select. Animation is state-driven, with transitions and path animation built in.

The performance claim deserves careful reading. The README's table compares 1,000,000 interactive rectangles against unnamed traditional Canvas libraries: first-screen creation around 1.28 seconds against roughly 9 to 15 seconds, memory around 320 MB against 2 to 4 GB, and single-element drag at 60 FPS against 0 to 4 FPS. The test environment is given as a 2K laptop running Chrome V143, and the README itself says the data is for reference and depends on hardware. The comparison baseline is not named, so treat the multipliers as the project's own framing rather than an independent measurement. The useful signal is the shape of the claim: creation time, memory, and interaction frame rate under a very large layer count. If your scenes are in the hundreds of elements, none of this is your bottleneck.

Installing leafer-ui and Drawing a Draggable Rectangle

The package installs from npm under the name leafer-ui. The README gives one important warning alongside the install: when you use plugins, it recommends installing the cross-platform core packages at the same time to avoid version skew between them.

npm install leafer-ui

# 需使用插件时，推荐同时安装跨平台核心包，防止出现更新版本不同步问题
npm install leafer-ui @leafer-ui/core @leafer-ui/draw

The package.json confirms the coupling. leafer-ui pins @leafer/core, @leafer/partner, @leafer/interface, @leafer-ui/draw, @leafer-ui/core, @leafer-ui/web, @leafer-ui/interaction-web, @leafer-ui/partner, @leafer-ui/interface, and @leafer-in/interface all at the same version. If you install a plugin that pulls a different version of one of those, you have two copies of the engine's internals in the bundle. That is the failure the README is warning about.

The first real use is short. Import Leafer and Rect, create a Leafer bound to the window, create a rectangle with position, size, fill, and draggable set, then add it.

import { Leafer, Rect } from 'leafer-ui'

// 创建一个自适应窗口的交互应用
const leafer = new Leafer({ view: window })

// 创建一个可以被拖拽的矩形
const rect = new Rect({
  x: 100,
  y: 100,
  width: 200,
  height: 200,
  fill: '#32cd79',
  draggable: true,
})

leafer.add(rect)

Passing window as the view makes the canvas fill the viewport and track resizes, per the comment in the example. You should see a green square at 100, 100 that responds to dragging without any pointer event code. The README links runnable versions of this and of an editor example on the project site, which is the fastest way to check behaviour before wiring it into an application. The package ships ESM, CommonJS, and a UMD build for unpkg and jsdelivr, with types at types/index.d.ts, so the same import works in a bundler and in a plain script tag.

Where leafer-ui Is the Wrong Choice

The engine runs on Canvas 2D. That is the source of its compatibility story and also its ceiling. If your workload is tens of thousands of points in a scatter plot, or GPU-accelerated 3D, or anything that wants a WebGL or WebGPU pipeline, a Canvas 2D engine is the wrong layer, and the million-rectangle figure does not change that. The README's own test is rectangles, which are cheap to rasterize; the memory number scales with the scene graph you build, not with the visual complexity of each element.

The second boundary is scope. leafer-ui is a rendering and interaction engine, not an application framework. It gives you a scene tree, layout, hit testing, and editing handles. It does not give you a document model, undo and redo, persistence, or collaboration. Those are the parts of a Figma-class editor that take the longest, and the README is explicit that the project draws a line between the engine and a mature product. It also notes that PxGrow offers optional commercial plugins aimed at industrial-grade problems: professional editor suites, complex graphic algorithms, and performance optimization. So the honest read is that some of what a serious editor needs may sit behind a commercial licence rather than in the MIT package.

Third, the API surface is large and the project ships on a fast release cadence, with v2.2.6, v2.2.7, and v2.2.9 all landing within about a week in late July and early August 2026. That is good for fixes and bad for pinning. If you depend on internal behaviour rather than the documented API, expect to re-check after upgrades. The README does not document a rollback procedure or a compatibility policy between minor versions, so plan to pin exact versions in your lockfile.

How It Differs From Konva and Charting Libraries

The closest comparison a reader will reach for is Konva, which also gives you a scene graph and hit testing on Canvas 2D. The difference is in what is built in. Konva leaves layout to you, so a flexbox-style arrangement means computing positions yourself or pulling in a separate layout pass. leafer-ui implements Flex layout inside the engine, which the README presents as unusual for this category. Editing is the other split: Konva has a transformer for resize and rotate, while leafer-ui ships an Editor plugin covering scale, rotate, move, and multi-select as one unit. The performance framing also differs: Konva does not advertise a million-element target, and leafer-ui's README builds its whole pitch around very large interactive layer counts.

Against a charting library such as ECharts or D3, the difference is categorical rather than incremental. Those tools own the mapping from data to marks and give you a fixed grammar of charts. leafer-ui owns the scene tree and gives you shapes. If you want a bar chart, a charting library is less work. If you want users to drag the bars, group them, resize a selection, and save the arrangement, you are building an editor, and a charting library will fight you the whole way. The README's own list of scenarios, from whiteboards to low-code engines to power-grid topology, is a list of editors.

The comparison to watch is the one the README itself makes: it positions leafer-ui as a Canvas core for a Figma-class editor rather than as a Figma alternative. Figma is a product with a document model and multiplayer; leafer-ui is the rendering and interaction layer you would build one on.

Licence, Maintenance, and Upgrade Cost

leafer-ui is MIT licensed, and the README states that the core features and basic plugins remain open source, with the project describing permanent open source under MIT as the goal. The package.json confirms the licence field as MIT. The practical implication is that you can use, modify, and redistribute the engine in commercial products without a separate agreement. That is a statement about the licence grant, not legal advice, and it does not extend to the separate commercial plugins from PxGrow, which are not part of this repository.

On maintenance, the last push to the repository was on 2026-08-02, and the most recent release given for the project is v2.2.9 on the same date. The repository is not archived. Three releases landed in the final week of July and the first days of August 2026, which tells you the project was moving quickly at that point; it does not tell you anything about the pace after that date, and the README is silent on it.

The upgrade cost is concentrated in one place: version alignment across the @leafer and @leafer-ui scopes. Because the packages are pinned to a shared version, an upgrade is not a single dependency bump. Install leafer-ui, @leafer-ui/core, and @leafer-ui/draw together as the README instructs, and keep your lockfile pinned. The README does not document a deprecation policy or a migration guide between minor versions, so the safe assumption is that a minor bump may change plugin behaviour and should be verified against your own scenes.

Editorial conclusion

Adopt leafer-ui if you are building an editor, whiteboard, or diagram tool where the scene graph is the product and you want a DOM-like API on Canvas. Do not adopt it if you need a charting library, a WebGL pipeline, or a rendering layer you can swap out. Before committing, install leafer-ui alongside @leafer-ui/core and @leafer-ui/draw at the same version, confirm the Flex layout and Editor plugin behave the way your design tool needs, and check whether the PxGrow commercial plugins cover the features you would otherwise build yourself.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes