react-konva

library19.2.3jsnpmunverified

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.

web-framework

npm install react-konva

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REACT-KONVA

react-konva

web-frameworkjavascriptv19.2.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Stage, Layer, Rect, Text

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

✗ import Stage from 'react-konva/Stage';

These are named exports for core Konva components wrapped for React.

useStrictMode

✓ import { useStrictMode } from 'react-konva';

✗ import useStrictMode from 'react-konva';

A named export hook/utility to configure strict mode globally for React Konva.

Konva

✓ import Konva from 'konva';

✗ import { Konva } from 'konva';

The underlying Konva library is typically imported as a default export from 'konva', not 'react-konva'.

Circle

✓ import { Circle } from 'react-konva';

✗ import Circle from 'react-konva';

All Konva shapes (e.g., Circle, Line, Image) are available as named exports from 'react-konva'.

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'));

Debug

Known issues

gotchaReact 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.

affects: >=1.0.0

gotchaUnderstanding 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.

affects: >=19.0.0

breakingCompatibility 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.

affects: >=19.0.0

breakingCompatibility 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.

affects: >=19.0.8

gotchaDouble 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.

affects: <19.0.6

Errors

Common errors & fixes

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.

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.

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>'.

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

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.

Upgrade

Version history

19.2.3latest on npm

Audit

Dependencies

konvarequiredCore 2D canvas framework that react-konva binds to.

reactrequiredEssential peer dependency for React component rendering.

react-domrequiredEssential peer dependency for React DOM rendering, often used for mounting the root React application.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/konvajs/react-konva ↗

packagehttps://www.npmjs.com/package/react-konva ↗

homepagehttps://konvajs.org/docs/react/ ↗