Vue Konva

Common errors

• Failed to resolve component: v-stage

  cause `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')

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

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

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

Warnings

• breaking 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`.
  Fix: For Vue 2 projects, use `npm install vue-konva@2 konva --save`. For Vue 3 projects, use `npm install vue-konva konva --save`.
• gotcha 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.
  Fix: Always wrap Konva properties in a `:config` prop object, e.g., `<v-circle :config="{ x: 100, fill: 'red' }"></v-circle>`.
• gotcha 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.
  Fix: Use `this.$refs.myRef.getNode()` (Options API) or `myRef.value.getNode()` (Composition API) to get the Konva instance.
• gotcha 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.
  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.

Install

• npm install vue-konva npm
• yarn add vue-konva yarn
• pnpm add vue-konva pnpm

Imports

• VueKonva
  wrong:

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

  correct:

  import VueKonva from '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)
  wrong:

  import { VStage } from 'vue-konva';

  correct:

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

  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()
  wrong:

  this.$refs.myKonvaComponentRef;

  correct:

  this.$refs.myKonvaComponentRef.getNode();

  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.

Quickstart

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>
*/