vue-konva

library3.4.0jsnpmunverified

Vue Konva is a JavaScript library that provides declarative and reactive bindings for the Konva Framework, enabling complex canvas graphics within Vue.js applications. It leverages Vue's component system to render Konva stages, layers, and shapes, abstracting away direct DOM manipulation. The current stable version, 3.4.0, primarily supports Vue 3 and Konva >7, with `vue-konva@2` maintained for Vue 2 compatibility. While there's no fixed release cadence, updates generally align with advancements in Vue.js and Konva.js to ensure continued integration. Its key differentiator is simplifying canvas interaction by mapping Konva objects to Vue components prefixed with 'v-', allowing developers to define canvas elements and their properties reactively using Vue's familiar template syntax and data flow, making complex canvas animations and interactions more manageable.

web-framework serialization

npm install vue-konva

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VUE-KONVA

vue-konva

web-frameworkjavascriptv3.4.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.

VueKonva

✓ import VueKonva from 'vue-konva';

✗ const VueKonva = require('vue-konva');

The primary plugin to register Vue Konva globally with `app.use()` in Vue 3 applications. `vue-konva` v3+ is ESM-first.

v-stage, v-layer, v-circle (components)

✓ <template><v-stage :config="..."><v-layer><v-circle :config="..."></v-circle></v-layer></v-stage></template>

✗ import { VStage } from 'vue-konva';

Vue Konva registers all its components (e.g., `v-stage`, `v-rect`, `v-circle`) globally when `VueKonva` is installed via `app.use()`, making them directly available in templates without individual imports.

getNode()

✓ this.$refs.myKonvaComponentRef.getNode();

✗ this.$refs.myKonvaComponentRef;

Use `getNode()` on a component's ref to access the underlying Konva object (e.g., `Konva.Stage`, `Konva.Layer`, `Konva.Rect`) for direct Konva API manipulation.

Konva types

✓ import type Konva from 'konva';

For TypeScript users, import types directly from the `konva` package for better type inference when working with raw Konva objects obtained via `getNode()` or when defining config interfaces.

This example demonstrates how to set up `vue-konva` with a Vue 3 application, globally registering the plugin, and then rendering a simple red circle and a blue rectangle on a canvas. It shows how to pass Konva properties via the `config` prop and make shapes draggable.

import { createApp } from 'vue'; import App from './App.vue'; import VueKonva from 'vue-konva'; const app = createApp(App); app.use(VueKonva); app.mount('#app'); // App.vue /* <template> <v-stage :config="configKonva"> <v-layer> <v-circle :config="configCircle"></v-circle> <v-rect :config="configRect"></v-rect> </v-layer> </v-stage> </template> <script setup lang="ts"> import { ref } from 'vue'; const configKonva = ref({ width: 400, height: 300 }); const configCircle = ref({ x: 100, y: 100, radius: 50, fill: "red", stroke: "black", strokeWidth: 4, draggable: true }); const configRect = ref({ x: 200, y: 150, width: 80, height: 60, fill: "blue", stroke: "darkblue", strokeWidth: 3, draggable: true }); </script> */

Debug

Known issues

breakingVue 2 and Vue 3 projects require different versions of `vue-konva`. Version 3.x+ (the latest) is for Vue 3 and Konva >7. For Vue 2 compatibility, you must explicitly install `vue-konva@2`.

fix

For Vue 2 projects, use `npm install vue-konva@2 konva --save`. For Vue 3 projects, use `npm install vue-konva konva --save`.

affects: >=3.0.0

gotchaAll Konva object properties (e.g., `x`, `y`, `fill`, `strokeWidth`) must be passed via the `config` prop object to `v-` components. Passing them directly as individual props (e.g., `<v-circle :x="100" :fill="'red'"></v-circle>`) will not work as expected and may cause reactivity issues or be ignored.

fix

Always wrap Konva properties in a `:config` prop object, e.g., `<v-circle :config="{ x: 100, fill: 'red' }"></v-circle>`.

affects: >=1.0.0

gotchaTo interact with the underlying Konva.js objects (e.g., calling `stage.toDataURL()`, `layer.draw()`, or direct Konva API methods), you must use the `getNode()` method on the Vue component's ref. Directly accessing the ref (e.g., `this.$refs.stage` or `stageRef.value`) will return the Vue component instance, not the Konva object itself.

fix

Use `this.$refs.myRef.getNode()` (Options API) or `myRef.value.getNode()` (Composition API) to get the Konva instance.

affects: >=1.0.0

gotchaBy default, `vue-konva` works in 'non-strict' mode. If you manually change properties of a Konva node obtained via `getNode()` (e.g., during drag-and-drop), these changes might not automatically synchronize back to the Vue component's `config` prop, leading to discrepancies if the `config` prop is later updated.

fix

For consistent reactivity, prefer updating the `config` prop directly rather than mutating Konva nodes obtained via `getNode()`. If direct mutation is necessary, consider implementing 'strict mode' as described in `vue-konva` documentation or manually synchronizing changes back to your `config` data.

affects: >=1.0.0

Errors

Common errors & fixes

Failed to resolve component: v-stage

`VueKonva` plugin was not correctly installed via `app.use()` (Vue 3) or `Vue.use()` (Vue 2), or the application did not correctly mount.

fix

Ensure `import VueKonva from 'vue-konva';` and `app.use(VueKonva);` (for Vue 3) are present in your main application entry file (e.g., `main.ts` or `main.js`).

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

Attempting to call `getNode()` on a Vue ref that has not yet been assigned to a mounted `vue-konva` component, or on a ref that points to a non-`vue-konva` element.

fix

Ensure the component is mounted before accessing its ref and calling `getNode()`, typically within `onMounted` (Composition API) or `mounted` (Options API) lifecycle hooks. Also, confirm the ref is correctly attached to a `v-` component.

[Vue warn]: Property "x" was accessed during render but is not defined on instance.

Konva properties like `x`, `y`, `fill`, etc., are being passed directly as props to a `v-` component instead of being encapsulated within the `:config` prop.

fix

Place all Konva-specific properties inside a single `config` object and bind it to the `v-` component using `:config`. For example, `<v-circle :config="{ x: 100, y: 100, fill: 'red' }"></v-circle>`.

Error: Konva error: You may only add layers to the stage.

Incorrect nesting of `vue-konva` components, specifically attempting to place shapes directly inside `v-stage` or other containers that are not `v-layer` or `v-group` components.

fix

Ensure `v-stage` contains `v-layer` components, and `v-layer` or `v-group` components contain your specific Konva shapes (`v-circle`, `v-rect`, etc.). Correct hierarchy is `<v-stage><v-layer><v-shape/></v-layer></v-stage>`.

Upgrade

Version history

3.4.0latest on npm

Audit

Dependencies

konvarequiredRequired Konva.js library for underlying canvas rendering and drawing logic.

vuerequiredPeer dependency for seamless integration with Vue.js applications. Version 3.x is required for `vue-konva` v3+.

Agent activity

33 hits · last 30 days

node

OpenAI (training)

Resources

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

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

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