konva

Konva.js is an HTML5 Canvas JavaScript framework that extends the 2d context by enabling canvas interactivity for desktop and mobile applications.

11,485

920

11,485

View on GitHub View on NPM

Top Related Projects

fabric.js

28,914

Javascript Canvas Library, SVG-to-Canvas (& canvas-to-SVG) Parser

pixijs

43,739

The HTML5 Creation Engine: Create beautiful digital content with the fastest, most flexible 2D WebGL renderer.

EaselJS

8,134

The Easel Javascript library provides a full, hierarchical display list, a core interaction model, and helper classes to make working with the HTML5 Canvas element much easier.

paper.js

14,462

The Swiss Army Knife of Vector Graphics Scripting – Scriptographer ported to JavaScript and the browser, using HTML5 Canvas. Created by @lehni & @puckey

Quick Overview

Konva is a powerful HTML5 Canvas JavaScript framework that extends the 2d context by enabling object interactivity on canvas. It provides high-performance animations, transitions, node nesting, layering, filtering, caching, event handling for desktop and mobile applications, and much more.

Pros

High performance for complex canvas applications
Rich set of features including shapes, animations, and event handling
Excellent documentation and community support
Cross-platform compatibility (works on desktop and mobile)

Cons

Learning curve for developers new to canvas-based applications
Can be overkill for simple drawing tasks
Performance may degrade with a large number of objects on canvas
Limited built-in support for responsive design

Code Examples

Creating a stage and adding a shape:

const stage = new Konva.Stage({
  container: 'container',
  width: 500,
  height: 500
});

const layer = new Konva.Layer();
stage.add(layer);

const circle = new Konva.Circle({
  x: 100,
  y: 100,
  radius: 50,
  fill: 'red'
});

layer.add(circle);
layer.draw();

Adding drag and drop functionality:

const rect = new Konva.Rect({
  x: 20,
  y: 20,
  width: 100,
  height: 50,
  fill: 'green',
  draggable: true
});

layer.add(rect);
layer.draw();

Creating a simple animation:

const anim = new Konva.Animation(function(frame) {
  const amplitude = 100;
  const period = 2000;
  circle.y(amplitude * Math.sin((frame.time * 2 * Math.PI) / period) + 150);
}, layer);

anim.start();

Getting Started

Include Konva in your project:

<script src="https://unpkg.com/konva@8.4.2/konva.min.js"></script>

Create a container for your canvas:

<div id="container"></div>

Initialize Konva and create your first shape:

const stage = new Konva.Stage({
  container: 'container',
  width: 400,
  height: 400
});

const layer = new Konva.Layer();
stage.add(layer);

const rect = new Konva.Rect({
  x: 50,
  y: 50,
  width: 100,
  height: 100,
  fill: 'blue',
  stroke: 'black',
  strokeWidth: 4
});

layer.add(rect);
layer.draw();

This will create a blue rectangle on your canvas. You can now start exploring more complex shapes, animations, and interactions using Konva's extensive API.

Competitor Comparisons

fabric.js

28,914

Javascript Canvas Library, SVG-to-Canvas (& canvas-to-SVG) Parser

Pros of Fabric.js

More comprehensive object model with built-in support for complex shapes and text
Better SVG import/export capabilities
Extensive documentation and larger community support

Cons of Fabric.js

Steeper learning curve due to more complex API
Slower performance for large numbers of objects compared to Konva

Code Comparison

Fabric.js:

var canvas = new fabric.Canvas('canvas');
var rect = new fabric.Rect({
  left: 100,
  top: 100,
  fill: 'red',
  width: 20,
  height: 20
});
canvas.add(rect);

Konva:

var stage = new Konva.Stage({
  container: 'container',
  width: 500,
  height: 500
});
var layer = new Konva.Layer();
var rect = new Konva.Rect({
  x: 100,
  y: 100,
  fill: 'red',
  width: 20,
  height: 20
});
layer.add(rect);
stage.add(layer);

Both libraries provide similar functionality for basic shape creation and manipulation. Fabric.js uses a canvas-centric approach, while Konva uses a stage and layer structure. Fabric.js offers more built-in features for complex objects, while Konva provides a simpler API and better performance for large numbers of objects.

pixijs

43,739

The HTML5 Creation Engine: Create beautiful digital content with the fastest, most flexible 2D WebGL renderer.

Pros of PixiJS

Optimized for WebGL rendering, offering superior performance for complex graphics and animations
Extensive plugin ecosystem and community support
Better suited for game development with built-in sprite management and scene graph

Cons of PixiJS

Steeper learning curve, especially for developers new to WebGL
Larger file size, which may impact initial load times
Less intuitive for simple 2D drawing tasks compared to Konva

Code Comparison

Konva:

const stage = new Konva.Stage({
  container: 'container',
  width: 500,
  height: 500
});
const layer = new Konva.Layer();
stage.add(layer);

PixiJS:

const app = new PIXI.Application({
  width: 500,
  height: 500,
  view: document.getElementById('container')
});
const container = new PIXI.Container();
app.stage.addChild(container);

Both libraries provide ways to create a stage or application and add layers or containers. PixiJS uses a more object-oriented approach with the Application class, while Konva separates the stage and layer concepts. PixiJS is generally more verbose but offers finer control over rendering options.

EaselJS

8,134

The Easel Javascript library provides a full, hierarchical display list, a core interaction model, and helper classes to make working with the HTML5 Canvas element much easier.

Pros of EaselJS

More comprehensive suite of tools (part of CreateJS)
Better suited for complex animations and game development
Stronger community support and ecosystem

Cons of EaselJS

Steeper learning curve due to more features
Larger file size, potentially impacting load times
Less frequent updates compared to Konva

Code Comparison

EaselJS:

var stage = new createjs.Stage("canvas");
var circle = new createjs.Shape();
circle.graphics.beginFill("red").drawCircle(0, 0, 50);
circle.x = 100;
circle.y = 100;
stage.addChild(circle);
stage.update();

Konva:

var stage = new Konva.Stage({
  container: 'container',
  width: 500,
  height: 500
});
var layer = new Konva.Layer();
var circle = new Konva.Circle({
  x: 100,
  y: 100,
  radius: 50,
  fill: 'red'
});
layer.add(circle);
stage.add(layer);

Both libraries offer similar functionality for creating and manipulating shapes on a canvas, but EaselJS uses a more traditional approach with a single stage, while Konva introduces the concept of layers for better organization and performance.

paper.js

14,462

The Swiss Army Knife of Vector Graphics Scripting – Scriptographer ported to JavaScript and the browser, using HTML5 Canvas. Created by @lehni & @puckey

Pros of Paper.js

More comprehensive vector graphics capabilities, including advanced path manipulation and boolean operations
Built-in support for mathematical expressions and complex calculations
Extensive documentation and tutorials for learning and implementation

Cons of Paper.js

Steeper learning curve due to its more complex API and unique scripting language (PaperScript)
Larger file size, which may impact load times for web applications
Less frequent updates and potentially slower community support

Code Comparison

Paper.js:

var path = new Path();
path.strokeColor = 'black';
path.moveTo(new Point(30, 75));
path.lineTo(new Point(30, 25));
path.lineTo(new Point(80, 25));

Konva:

var line = new Konva.Line({
  points: [30, 75, 30, 25, 80, 25],
  stroke: 'black',
  strokeWidth: 2
});
layer.add(line);

Both libraries allow for creating and manipulating shapes, but Paper.js uses a more object-oriented approach with separate methods for each action, while Konva uses a more concise, configuration-based syntax. Paper.js offers more granular control over path creation, which can be beneficial for complex vector graphics, while Konva's approach is often simpler for basic shapes and common use cases.

three.js

101,622

JavaScript 3D Library.

Pros of Three.js

More powerful 3D rendering capabilities
Larger community and ecosystem
Extensive documentation and examples

Cons of Three.js

Steeper learning curve
Heavier library size
Overkill for simple 2D graphics

Code Comparison

Three.js (3D scene):

const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
const renderer = new THREE.WebGLRenderer();
renderer.setSize(window.innerWidth, window.innerHeight);
document.body.appendChild(renderer.domElement);

Konva (2D canvas):

const stage = new Konva.Stage({
  container: 'container',
  width: window.innerWidth,
  height: window.innerHeight
});
const layer = new Konva.Layer();
stage.add(layer);

Three.js is a powerful 3D graphics library, while Konva focuses on 2D canvas manipulation. Three.js offers more advanced features for 3D rendering but has a steeper learning curve. Konva is simpler and more lightweight, making it ideal for 2D graphics and interactive applications. Three.js has a larger community and more extensive documentation, but Konva is easier to get started with for 2D projects. Choose Three.js for complex 3D visualizations and Konva for efficient 2D canvas-based applications.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Konva logo

Konva

Konva is an HTML5 Canvas JavaScript framework that enables high performance animations, transitions, node nesting, layering, filtering, caching, event handling for desktop and mobile applications, and much more.

You can draw things onto the stage, add event listeners to them, move them, scale them, and rotate them independently from other shapes to support high performance animations, even if your application uses thousands of shapes. Served hot with a side of awesomeness.

This repository began as a GitHub fork of ericdrowell/KineticJS.

Visit: The Home Page and follow on Twitter
Discover: Tutorials, API Documentation
Help: StackOverflow, Discord Chat

Quick Look

<script src="https://unpkg.com/konva@9/konva.min.js"></script>
<div id="container"></div>
<script>
  var stage = new Konva.Stage({
    container: 'container',
    width: window.innerWidth,
    height: window.innerHeight,
  });

  // add canvas element
  var layer = new Konva.Layer();
  stage.add(layer);

  // create shape
  var box = new Konva.Rect({
    x: 50,
    y: 50,
    width: 100,
    height: 50,
    fill: '#00D2FF',
    stroke: 'black',
    strokeWidth: 4,
    draggable: true,
  });
  layer.add(box);

  // add cursor styling
  box.on('mouseover', function () {
    document.body.style.cursor = 'pointer';
  });
  box.on('mouseout', function () {
    document.body.style.cursor = 'default';
  });
</script>

Browsers support

Konva works in all modern mobile and desktop browsers. A browser need to be capable to run javascript code from ES2015 spec. For older browsers you may need polyfills for missing functions.

At the current moment Konva doesn't work in IE11 directly. To make it work you just need to provide some polyfills such as Array.prototype.find, String.prototype.trimLeft, String.prototype.trimRight, Array.from.

Debugging

The Chrome inspector simply shows the canvas element. To see the Konva objects and their details, install the konva-dev extension at https://github.com/konvajs/konva-devtool.

Loading and installing Konva

Konva supports UMD loading. So you can use all possible variants to load the framework into your project:

Load Konva via classical `<script>` tag from CDN:

<script src="https://unpkg.com/konva@9/konva.min.js"></script>

Install with npm:

npm install konva --save

// The modern way (e.g. an ES6-style import for webpack, parcel)
import Konva from 'konva';

Typescript usage

Add DOM definitions into your tsconfig.json:

{
  "compilerOptions": {
    "lib": [
        "es6",
        "dom"
    ]
  }
}

3 Minimal bundle

import Konva from 'konva/lib/Core';
// Now you have a Konva object with Stage, Layer, FastLayer, Group, Shape and some additional utils function.
// Also core currently already have support for drag&drop and animations.
// BUT there are no shapes (rect, circle, etc), no filters.

// but you can simply add anything you need:
import { Rect } from 'konva/lib/shapes/Rect';
// importing a shape will automatically inject it into Konva object

var rect1 = new Rect();
// or:
var shape = new Konva.Rect();

// for filters you can use this:
import { Blur } from 'konva/lib/filters/Blur';

4 NodeJS env

In order to run konva in nodejs environment you also need to install canvas package manually. Konva will use it for 2d canvas API.

npm install konva canvas

Then you can use the same Konva API and all Konva demos will work just fine. You just don't need to use container attribute in your stage.

import Konva from 'konva';

const stage = new Konva.Stage({
  width: 500,
  height: 500,
});
// then all regular Konva code will work

Backers

Change log

See CHANGELOG.md.

Building the Konva Framework

To make a full build run npm run build. The command will compile all typescript files, combine then into one bundle and run minifier.

Testing

Konva uses Mocha for testing.

If you need run test only one time run npm run test.
While developing it is easy to use npm start. Just run it and go to http://localhost:1234/unit-tests.html. The watcher will rebuild the bundle on any change.

Konva is covered with hundreds of tests and well over a thousand assertions. Konva uses TDD (test driven development) which means that every new feature or bug fix is accompanied with at least one new test.

Generate documentation

Run npx gulp api which will build the documentation files and place them in the api folder.

Pull Requests

I'd be happy to review any pull requests that may better the Konva project, in particular if you have a bug fix, enhancement, or a new shape (see src/shapes for examples). Before doing so, please first make sure that all of the tests pass (npm run test).