{"id":18059,"library":"react-konva-utils","title":"React Konva Utilities","description":"react-konva-utils is a supplementary library providing useful components and hooks for `react-konva` applications. As of its current stable version 2.0.0, it offers key functionalities such as the `Html` component for seamlessly embedding standard DOM elements within a Konva stage and the `Portal` component for relocating Konva nodes within the stage's rendering hierarchy. This package is designed to simplify complex UI scenarios that require blending canvas-rendered graphics with interactive HTML elements. It maintains compatibility with recent major versions of its peer dependencies, including `react` (v18/v19), `react-dom` (v18/v19), `konva` (v8/v9/v10), and `react-konva` (v18/v19), aligning its release cadence with these core libraries. Its primary differentiation lies in abstracting away the manual DOM manipulation and complex node management often required to achieve advanced canvas-DOM integrations.","status":"active","version":"2.0.0","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","react","canvas","konva","react-konva","typescript"],"install":[{"cmd":"npm install react-konva-utils","lang":"bash","label":"npm"},{"cmd":"yarn add react-konva-utils","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-konva-utils","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core canvas library that react-konva-utils integrates with for rendering canvas elements.","package":"konva","optional":false},{"reason":"Fundamental library for building user interfaces, a core requirement for any React-based Konva application.","package":"react","optional":false},{"reason":"Provides DOM-specific methods, necessary for rendering React components, especially crucial for the Html component which interacts with the browser's DOM.","package":"react-dom","optional":false},{"reason":"The primary wrapper library that react-konva-utils extends, providing React components for Konva nodes.","package":"react-konva","optional":false}],"imports":[{"note":"react-konva-utils is an ESM-first library. While CJS might work via transpilation, direct ESM imports are preferred for modern React projects.","wrong":"const { Html } = require('react-konva-utils');","symbol":"Html","correct":"import { Html } from 'react-konva-utils';"},{"note":"Named export `Portal` should be destructured from the main package. Importing from subpaths is not officially supported and can break.","wrong":"import Portal from 'react-konva-utils/dist/Portal';","symbol":"Portal","correct":"import { Portal } from 'react-konva-utils';"},{"note":"When importing only types, use `import type` for better tree-shaking and to explicitly indicate it's a type-only import, especially with TypeScript.","wrong":"import { HtmlProps } from 'react-konva-utils';","symbol":"HtmlProps","correct":"import type { HtmlProps } from 'react-konva-utils';"}],"quickstart":{"code":"import React from 'react';\nimport { Stage, Layer, Rect } from 'react-konva';\nimport { Html } from 'react-konva-utils';\n\nconst App = () => {\n const stageWidth = window.innerWidth;\n const stageHeight = window.innerHeight;\n\n return (\n \n \n \n \n
\n

Konva HTML Overlay

\n

\n This is a standard DOM element rendered over the canvas.\n

\n alert('Button in HTML clicked!')}\n style={{ marginTop: '10px', padding: '8px 12px', cursor: 'pointer' }}\n >\n Click Me!\n \n
\n \n \n \n \n );\n};\n\nexport default App;\n","lang":"typescript","description":"This quickstart demonstrates how to embed and position standard HTML content directly onto a Konva canvas using the `Html` component. It showcases interactive DOM elements within a canvas scene, allowing for rich UI overlays."},"warnings":[{"fix":"Design your application such that critical, exportable content is rendered directly with Konva shapes. If HTML content must be included in exports, consider using a separate DOM-to-image library to capture the HTML, or redraw the content using Konva shapes programmatically.","message":"The `Html` component renders standard DOM elements *over* the Konva canvas, not within it. This means any content rendered via `Html` will *not* be included when exporting the canvas to an image (e.g., `stage.toDataURL()`).","severity":"gotcha","affected_versions":"all versions"},{"fix":"Check your `package.json` for `konva`, `react`, `react-dom`, and `react-konva`. Upgrade or downgrade them to satisfy the ranges specified in `react-konva-utils`'s peer dependencies (e.g., `npm install konva@^10 react@^18 react-dom@^18 react-konva@^19`).","message":"Using `react-konva-utils` with incompatible versions of `konva`, `react`, `react-dom`, or `react-konva` can lead to runtime errors, unexpected rendering, or an inability to use core features. Refer to peer dependency ranges to ensure compatibility.","severity":"breaking","affected_versions":"all versions"},{"fix":"If you are manually controlling the position or style of the HTML content via `divProps.style` or external CSS, set `transform={false}` on the `Html` component to prevent automatic Konva transformations from interfering. Only enable `transform` if you want `Html` to automatically follow the Konva stage's transformations.","message":"The `Html` component's `transform` prop (which defaults to `true`) automatically applies Konva's position and scale transformations to the underlying DOM element. If you are also applying CSS transformations or manually positioning the `divProps` container, it can lead to double transformations or misaligned content.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Keep `Html` content as simple as possible. For static or infrequently updated content, this is less of an issue. For highly interactive elements, consider if they can be represented as pure Konva shapes or if their updates can be throttled to reduce DOM reflows and repaints.","message":"Embedding highly dynamic or complex DOM structures within the `Html` component, especially those with frequent updates, can lead to performance degradation. While Konva renders efficiently on the canvas, the `Html` component involves standard DOM manipulation which can be costly for complex or rapidly changing content.","severity":"gotcha","affected_versions":"all versions"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Ensure `parentNodeFunc` always returns a valid DOM element where the HTML content should be appended. The default is `stage?.container()`, which typically works if the Konva stage is properly initialized.","cause":"The `parentNodeFunc` prop provided to the `Html` component returned `null`, `undefined`, or a non-DOM element, preventing the HTML content from being mounted correctly.","error":"Error: The `parentNodeFunc` prop in `Html` must return a valid DOM node."},{"fix":"Ensure that children passed to the `Portal` component are valid `react-konva` components (e.g., `Rect`, `Circle`, `Group`). Standard HTML elements or non-Konva React components cannot directly receive Konva transformation props.","cause":"Attempting to pass Konva-specific props (like `x`, `y`, `draggable`) to a non-Konva component, or passing non-Konva components directly as children to the `Portal` component.","error":"TypeError: Cannot read properties of undefined (reading 'x')"},{"fix":"Verify that a `Konva.Group` or `Konva.Layer` with the specified `name` or `id` (e.g., ``) exists within the Konva stage. The selector must target a valid Konva node that can act as a container for other nodes.","cause":"The `selector` prop provided to the `Portal` component does not correspond to an existing `Konva.Group` or `Konva.Layer` element within the Konva stage hierarchy, or targets an invalid Konva node type.","error":"Error: The `selector` prop for `Portal` must be a valid CSS selector string for a Konva `Group` or `Layer`."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}