{"id":15272,"library":"vue-konva","title":"Vue Konva","description":"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.","status":"active","version":"3.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/konvajs/vue-konva","tags":["javascript","vue","konva","canvas","typescript"],"install":[{"cmd":"npm install vue-konva","lang":"bash","label":"npm"},{"cmd":"yarn add vue-konva","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-konva","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required Konva.js library for underlying canvas rendering and drawing logic.","package":"konva","optional":false},{"reason":"Peer dependency for seamless integration with Vue.js applications. Version 3.x is required for `vue-konva` v3+.","package":"vue","optional":false}],"imports":[{"note":"The primary plugin to register Vue Konva globally with `app.use()` in Vue 3 applications. `vue-konva` v3+ is ESM-first.","wrong":"const VueKonva = require('vue-konva');","symbol":"VueKonva","correct":"import VueKonva from 'vue-konva';"},{"note":"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.","wrong":"import { VStage } from 'vue-konva';","symbol":"v-stage, v-layer, v-circle (components)","correct":"<template><v-stage :config=\"...\"><v-layer><v-circle :config=\"...\"></v-circle></v-layer></v-stage></template>"},{"note":"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.","wrong":"this.$refs.myKonvaComponentRef;","symbol":"getNode()","correct":"this.$refs.myKonvaComponentRef.getNode();"},{"note":"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.","symbol":"Konva types","correct":"import type Konva from 'konva';"}],"quickstart":{"code":"import { createApp } from 'vue';\nimport App from './App.vue';\nimport VueKonva from 'vue-konva';\n\nconst app = createApp(App);\napp.use(VueKonva);\napp.mount('#app');\n\n// App.vue\n/*\n<template>\n  <v-stage :config=\"configKonva\">\n    <v-layer>\n      <v-circle :config=\"configCircle\"></v-circle>\n      <v-rect :config=\"configRect\"></v-rect>\n    </v-layer>\n  </v-stage>\n</template>\n\n<script setup lang=\"ts\">\nimport { ref } from 'vue';\n\nconst configKonva = ref({\n  width: 400,\n  height: 300\n});\n\nconst configCircle = ref({\n  x: 100,\n  y: 100,\n  radius: 50,\n  fill: \"red\",\n  stroke: \"black\",\n  strokeWidth: 4,\n  draggable: true\n});\n\nconst configRect = ref({\n  x: 200,\n  y: 150,\n  width: 80,\n  height: 60,\n  fill: \"blue\",\n  stroke: \"darkblue\",\n  strokeWidth: 3,\n  draggable: true\n});\n</script>\n*/","lang":"typescript","description":"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."},"warnings":[{"fix":"For Vue 2 projects, use `npm install vue-konva@2 konva --save`. For Vue 3 projects, use `npm install vue-konva konva --save`.","message":"Vue 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`.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Always wrap Konva properties in a `:config` prop object, e.g., `<v-circle :config=\"{ x: 100, fill: 'red' }\"></v-circle>`.","message":"All 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use `this.$refs.myRef.getNode()` (Options API) or `myRef.value.getNode()` (Composition API) to get the Konva instance.","message":"To 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"By 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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`).","cause":"`VueKonva` plugin was not correctly installed via `app.use()` (Vue 3) or `Vue.use()` (Vue 2), or the application did not correctly mount.","error":"Failed to resolve component: v-stage"},{"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.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'getNode')"},{"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>`.","cause":"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.","error":"[Vue warn]: Property \"x\" was accessed during render but is not defined on instance."},{"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>`.","cause":"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.","error":"Error: Konva error: You may only add layers to the stage."}],"ecosystem":"npm"}