Registry / web-framework / react-konva-utils

react-konva-utils

library2.0.0jsnpmunverified

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.

web-framework

npm install react-konva-utils

package ↗

INSTALL

IMPORT

SIG · REACT-KONVA-UTILS

react-konva-utils

web-frameworkjavascriptv2.0.0

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.

Html

✓ import { Html } from 'react-konva-utils';

✗ const { Html } = require('react-konva-utils');

react-konva-utils is an ESM-first library. While CJS might work via transpilation, direct ESM imports are preferred for modern React projects.

Portal

✓ import { Portal } from 'react-konva-utils';

✗ import Portal from 'react-konva-utils/dist/Portal';

Named export `Portal` should be destructured from the main package. Importing from subpaths is not officially supported and can break.

HtmlProps

✓ import type { HtmlProps } from 'react-konva-utils';

✗ import { HtmlProps } from 'react-konva-utils';

When importing only types, use `import type` for better tree-shaking and to explicitly indicate it's a type-only import, especially with TypeScript.

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.

import React from 'react'; import { Stage, Layer, Rect } from 'react-konva'; import { Html } from 'react-konva-utils'; const App = () => { const stageWidth = window.innerWidth; const stageHeight = window.innerHeight; return ( <Stage width={stageWidth} height={stageHeight}> <Layer> <Rect x={50} y={50} width={100} height={100} fill="blue" /> <Html transform groupProps={{ x: 120, y: 120 }} divProps={{ style: { background: 'white', padding: '10px', border: '2px solid #ccc', borderRadius: '5px', boxShadow: '0px 2px 5px rgba(0,0,0,0.2)' } }} > <div> <h3 style={{ margin: '0 0 8px 0', color: '#333' }}>Konva HTML Overlay</h3> <p style={{ margin: '0', fontSize: '14px', color: '#555' }}> This is a standard DOM element rendered over the canvas. </p> <button onClick={() => alert('Button in HTML clicked!')} style={{ marginTop: '10px', padding: '8px 12px', cursor: 'pointer' }} > Click Me! </button> </div> </Html> <Rect x={300} y={250} width={150} height={80} fill="green" /> </Layer> </Stage> ); }; export default App;

Debug

Known issues

gotchaThe `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()`).

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.

affects: all versions

breakingUsing `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.

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`).

affects: all versions

gotchaThe `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.

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.

affects: >=2.0.0

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

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.

affects: all versions

Errors

Common errors & fixes

Error: The `parentNodeFunc` prop in `Html` must return a valid DOM node.

The `parentNodeFunc` prop provided to the `Html` component returned `null`, `undefined`, or a non-DOM element, preventing the HTML content from being mounted correctly.

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.

TypeError: Cannot read properties of undefined (reading 'x')

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.

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.

Error: The `selector` prop for `Portal` must be a valid CSS selector string for a Konva `Group` or `Layer`.

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.

fix

Verify that a `Konva.Group` or `Konva.Layer` with the specified `name` or `id` (e.g., `<Group name='my-target' />`) exists within the Konva stage. The selector must target a valid Konva node that can act as a container for other nodes.

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

konvarequiredCore canvas library that react-konva-utils integrates with for rendering canvas elements.

reactrequiredFundamental library for building user interfaces, a core requirement for any React-based Konva application.

react-domrequiredProvides DOM-specific methods, necessary for rendering React components, especially crucial for the Html component which interacts with the browser's DOM.

react-konvarequiredThe primary wrapper library that react-konva-utils extends, providing React components for Konva nodes.

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

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