{"id":11739,"library":"react-konva","title":"React Konva","description":"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.","status":"active","version":"19.2.3","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/konvajs/react-konva","tags":["javascript","react","canvas","jsx","konva","typescript"],"install":[{"cmd":"npm install react-konva","lang":"bash","label":"npm"},{"cmd":"yarn add react-konva","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-konva","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core 2D canvas framework that react-konva binds to.","package":"konva","optional":false},{"reason":"Essential peer dependency for React component rendering.","package":"react","optional":false},{"reason":"Essential peer dependency for React DOM rendering, often used for mounting the root React application.","package":"react-dom","optional":false}],"imports":[{"note":"These are named exports for core Konva components wrapped for React.","wrong":"import Stage from 'react-konva/Stage';","symbol":"Stage, Layer, Rect, Text","correct":"import { Stage, Layer, Rect, Text } from 'react-konva';"},{"note":"A named export hook/utility to configure strict mode globally for React Konva.","wrong":"import useStrictMode from 'react-konva';","symbol":"useStrictMode","correct":"import { useStrictMode } from 'react-konva';"},{"note":"The underlying Konva library is typically imported as a default export from 'konva', not 'react-konva'.","wrong":"import { Konva } from 'konva';","symbol":"Konva","correct":"import Konva from 'konva';"},{"note":"All Konva shapes (e.g., Circle, Line, Image) are available as named exports from 'react-konva'.","wrong":"import Circle from 'react-konva';","symbol":"Circle","correct":"import { Circle } from 'react-konva';"}],"quickstart":{"code":"import React, { useState } from 'react';\nimport { render } from 'react-dom';\nimport { Stage, Layer, Rect, Text } from 'react-konva';\nimport Konva from 'konva';\n\nconst ColoredRect = () => {\n  const [color, setColor] = useState('green');\n\n  const handleClick = () => {\n    setColor(Konva.Util.getRandomColor());\n  };\n\n  return <Rect x={20} y={20} width={50} height={50} fill={color} shadowBlur={5} onClick={handleClick} />;\n};\n\nconst App = () => {\n  return (\n    <Stage width={window.innerWidth} height={window.innerHeight}>\n      <Layer>\n        <Text text=\"Try click on rect\" />\n        <ColoredRect />\n      </Layer>\n    </Stage>\n  );\n};\n\nrender(<App />, document.getElementById('root'));","lang":"javascript","description":"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."},"warnings":[{"fix":"Use a different library specifically designed for React Native canvas or drawing if targeting mobile native platforms.","message":"React Konva is not supported in React Native environments. It is specifically designed for web-based applications using the HTML5 canvas.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=19.0.0"},{"fix":"Ensure your project uses `react@^19.2.0` and `react-dom@^19.2.0` when using react-konva v19.x.","message":"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.","severity":"breaking","affected_versions":">=19.0.0"},{"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.","message":"Compatibility with Konva v10. React Konva v19.0.8 added support for Konva v10. Earlier v19 versions might have limited or no compatibility.","severity":"breaking","affected_versions":">=19.0.8"},{"fix":"Update to react-konva v19.0.6 or newer to resolve issues with double event attachments when using React's Strict Mode.","message":"Double event attachments in React Strict Mode were a known issue in earlier v19 versions, leading to unexpected event behavior.","severity":"gotcha","affected_versions":"<19.0.6"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Attempting to render a raw Konva object or an incorrect JSX structure directly within a React component.","error":"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."},{"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.","cause":"Placing Konva shapes directly inside `<Stage>` instead of wrapping them in a `<Layer>`. The `<Stage>` component is a container for `<Layer>` components.","error":"\"Konva component\" is not a <Stage> child. <Stage> can only contain <Layer> children."},{"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.","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.","error":"Property 'current' does not exist on type 'MutableRefObject<undefined>'."},{"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.","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.","error":"ReferenceError: window is not defined"}],"ecosystem":"npm"}