React Konva

19.2.3 · active · verified Sun Apr 19

React Konva provides declarative and reactive bindings for integrating the Konva 2D canvas framework into React applications. It allows developers to use Konva's rich set of shapes, layers, and stage components as standard React components, enabling a familiar declarative JSX syntax for canvas drawing. The library is currently at version 19.2.3, frequently releasing patch and minor updates to ensure compatibility with the latest React and Konva versions. Its primary differentiator is leveraging React's component model and data flow for high-performance canvas rendering, abstracting away direct DOM manipulation. It is built on top of the Konva framework, meaning users primarily need to understand Konva's API and concepts to effectively use React Konva.

Common errors

```
Objects are not valid as a React child (found: object with keys {x, y, ...}). If you meant to render a collection of children, use an array instead.
```
cause Attempting to render a raw Konva object or an incorrect JSX structure directly within a React component.

fix Ensure all children within `<Stage>` and `<Layer>` are valid React-Konva components (e.g., `<Rect>`, `<Circle>`) and not raw Konva instances or other non-renderable objects.
```
"Konva component" is not a <Stage> child. <Stage> can only contain <Layer> children.
```
cause Placing Konva shapes directly inside `<Stage>` instead of wrapping them in a `<Layer>`. The `<Stage>` component is a container for `<Layer>` components.

fix All visual Konva components (e.g., `<Rect>`, `<Circle>`, `<Text>`) must be nested inside a `<Layer>` component, which in turn is a child of the `<Stage>` component.
```
Property 'current' does not exist on type 'MutableRefObject<undefined>'.
```
cause Accessing the `.current` property of a `useRef` hook before the component has mounted or before the ref has been assigned to the Konva node instance.

fix Ensure you access `ref.current` within a `useEffect` hook with an empty dependency array (`[]`) to guarantee the component is mounted and the ref has been assigned to the Konva node instance.
```
ReferenceError: window is not defined
```
cause Attempting to use `window.innerWidth` or `window.innerHeight` (or other browser-specific globals) in a server-side rendering (SSR) context, where `window` is not available.

fix For SSR, conditionally render the `<Stage>` component only on the client-side, provide default dimensions, or use a client-only rendering approach for the canvas component if browser globals are required for initial sizing.

Warnings

gotcha React Konva is not supported in React Native environments. It is specifically designed for web-based applications using the HTML5 canvas.
Fix: Use a different library specifically designed for React Native canvas or drawing if targeting mobile native platforms.
gotcha Understanding Konva's "Strict Mode" is crucial for managing component property updates. By default, react-konva only updates properties changed in render(). In strict mode, all properties are updated to match render() values, potentially overwriting manual changes.
Fix: Enable strict mode globally with `useStrictMode(true)` or per-component with the `_useStrictMode` prop if you need all properties to always reflect the render function's state, especially when dealing with external manipulations or complex animations.
breaking Compatibility with React 19. React Konva v19 requires React 19.2.0 or higher. Earlier versions of react-konva are not compatible with React 19.
Fix: Ensure your project uses `react@^19.2.0` and `react-dom@^19.2.0` when using react-konva v19.x.
breaking Compatibility with Konva v10. React Konva v19.0.8 added support for Konva v10. Earlier v19 versions might have limited or no compatibility.
Fix: When using Konva v10, ensure react-konva is at least v19.0.8. Check your package.json for peer dependency ranges and update accordingly.
gotcha Double event attachments in React Strict Mode were a known issue in earlier v19 versions, leading to unexpected event behavior.
Fix: Update to react-konva v19.0.6 or newer to resolve issues with double event attachments when using React's Strict Mode.

Install

npm install react-konva npm
yarn add react-konva yarn
pnpm add react-konva pnpm

Imports

Stage, Layer, Rect, Text
wrong:
```
import Stage from 'react-konva/Stage';
```
correct:
```
import { Stage, Layer, Rect, Text } from 'react-konva';
```
These are named exports for core Konva components wrapped for React.
useStrictMode
wrong:
```
import useStrictMode from 'react-konva';
```
correct:
```
import { useStrictMode } from 'react-konva';
```
A named export hook/utility to configure strict mode globally for React Konva.
Konva
wrong:
```
import { Konva } from 'konva';
```
correct:
```
import Konva from 'konva';
```
The underlying Konva library is typically imported as a default export from 'konva', not 'react-konva'.
Circle
wrong:
```
import Circle from 'react-konva';
```
correct:
```
import { Circle } from 'react-konva';
```
All Konva shapes (e.g., Circle, Line, Image) are available as named exports from 'react-konva'.

Quickstart

This example demonstrates how to create a basic Konva stage with a layer, a text element, and a clickable colored rectangle using React state and event handlers.

import React, { useState } from 'react';
import { render } from 'react-dom';
import { Stage, Layer, Rect, Text } from 'react-konva';
import Konva from 'konva';

const ColoredRect = () => {
  const [color, setColor] = useState('green');

  const handleClick = () => {
    setColor(Konva.Util.getRandomColor());
  };

  return <Rect x={20} y={20} width={50} height={50} fill={color} shadowBlur={5} onClick={handleClick} />;
};

const App = () => {
  return (
    <Stage width={window.innerWidth} height={window.innerHeight}>
      <Layer>
        <Text text="Try click on rect" />
        <ColoredRect />
      </Layer>
    </Stage>
  );
};

render(<App />, document.getElementById('root'));

view raw JSON →