konvajs/react-konva

README

React Konva

React Konva provides declarative React components for the Konva 2D canvas scene graph. Use it to build design editors, whiteboards, diagrams, annotations, and other interactive graphics.

React Konva is MIT licensed. It supports Konva shapes and events. It does not support React Native.

Install

React Konva 19.3 requires React and React DOM ^19.3.0. For React 19.2, install the latest React Konva 19.2 release. For React 18, install the latest React Konva 18 release.

npm install react-konva konva

Quick example

import {useState} from 'react';
import {Stage, Layer, Rect} from 'react-konva';

export default function App() {
  const [color, setColor] = useState('#00a8e8');
  return (
    <Stage width={600} height={400}>
      <Layer>
        <Rect
          x={50} y={50} width={120} height={80}
          fill={color} draggable
          onClick={() => setColor(color === '#00a8e8' ? '#ff7a00' : '#00a8e8')}
        />
      </Layer>
    </Stage>
  );
}

Building a full design editor? Polotno is a commercial design editor SDK built on Konva by the Konva maintainers. It ships templates, text editing, and export, so you integrate an editor instead of building one: npm install polotno.

react-konva follows the Konva API. See the Konva overview for the scene graph, properties, and events.

Core API

react-konva supports Konva shapes with the same names. Event props use React names such as onClick, onTouchMove, and onDragEnd.

Getting reference to Konva objects

Use ref to access the underlying Konva node.

import React, { useEffect, useRef } from 'react';
import { Circle } from 'react-konva';

const MyShape = () => {
  const circleRef = useRef();

  useEffect(() => {
    // log Konva.Circle instance
    console.log(circleRef.current);
  }, []);

  return <Circle ref={circleRef} radius={50} fill="black" />;
};

React features inside Stage

Components inside Stage use React hooks and inherit context from the surrounding React tree.

Stage creates a separate canvas root. Place error and Suspense boundaries inside Stage, with Konva elements as fallbacks.

See the React compatibility matrix for hook support and renderer limits.

Strict mode

By default, react-konva updates only props that change between renders. Manual changes, such as a dragged position, persist until the corresponding prop changes.

Strict mode restores all supplied props to their rendered values on each update. For example, a circle with x={0} and y={0} returns to that position after a drag and a React update. This mode is separate from React's StrictMode.

To enable strict mode globally:

import { useStrictMode } from 'react-konva';

useStrictMode(true);

To enable strict mode for one node:

<Rect width={50} height={50} fill="black" _useStrictMode />

Minimal bundle

The default package includes all Konva shapes and filters. For a smaller bundle, use the core entry point and import individual shapes:

import { Stage, Layer, Rect } from 'react-konva/lib/ReactKonvaCore';

import 'konva/lib/shapes/Rect';

Demo: https://codesandbox.io/s/6l97wny44z

Usage with Next.js

Konva 10+ works with Next.js without extra canvas setup. Use a Client Component ('use client').

Konva 9 and earlier need extra setup, such as installing canvas or disabling SSR for the canvas component.

Event synchronization

With Konva 10.5+, React state updates from native input commit before the event finishes. To batch MobX reactions too, pass runInAction:

import { runInAction } from 'mobx';

<Stage eventBatchFunc={runInAction} width={600} height={400}>
  {/* Existing layers, shapes, and handlers */}
</Stage>

The wrapper must call its callback exactly once, synchronously. Older Konva versions ignore this prop.

With Konva 10.9+, react-konva also batches Transformer updates automatically across each canvas commit. See the release notes for geometry timing and compatibility details.

Development and tests

Use Node.js 24 LTS for development.

npm install
npx playwright install chromium
npm test

npm test covers development and production builds, performance counts, server rendering, package exports, and types. Set BROWSER=firefox or BROWSER=webkit to use another installed Playwright browser. See the benchmark guide for performance checks and timing comparisons.

CHANGELOG