https://github.com/konvajs/svelte-konva
Svelte & Canvas - JavaScript library for drawing complex canvas graphics using Svelte.
https://github.com/konvajs/svelte-konva
canvas konva svelte
Last synced: 5 months ago
JSON representation
Svelte & Canvas - JavaScript library for drawing complex canvas graphics using Svelte.
- Host: GitHub
- URL: https://github.com/konvajs/svelte-konva
- Owner: konvajs
- License: mit
- Created: 2022-09-22T16:43:46.000Z (about 3 years ago)
- Default Branch: master
- Last Pushed: 2025-05-05T23:32:56.000Z (5 months ago)
- Last Synced: 2025-05-07T02:27:54.661Z (5 months ago)
- Topics: canvas, konva, svelte
- Language: TypeScript
- Homepage: https://konvajs.org/docs/svelte/
- Size: 3.24 MB
- Stars: 81
- Watchers: 6
- Forks: 6
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# svelte-konva
[](https://www.npmjs.com/package/svelte-konva)
[](https://konvajs.org/docs/svelte)
svelte-konva is a component-based svelte wrapper for the [Konva HTML5 2D canvas library](https://github.com/konvajs/konva). For further information and examples please visit the [docs](https://konvajs.org/docs/svelte).
## Compatibility
Currently compatible with Svelte v3 & 4, SvelteKit v1 and Konva v8 & 9.
### Experimental Svelte 5 support
There is now experimental support for Svelte v5. It is not production-ready and should be used for testing purposes only. Svelte 5 support is currently published under the `v1.0.0-next` tag. To use it simply add the following dependency to your package.json in your Svelte 5 project:
```
"svelte-konva": "^1.0.0-next.0"
```
Please see the [migration guide](./docs/svelte-konva-v1-migration.md) for all relevant (and breaking) changes.
If you encounter bugs or difficulties while migrating/testing please open an issue.
## Install
```npm
npm i svelte-konva konva
```
## Quick start
```svelte
import { Stage, Layer, Rect } from 'svelte-konva';
```
### Events
You can listen to Konva events by using the Svelte `on:event` Syntax. All [Konva events](https://konvajs.org/docs/events/Binding_Events.html) are supported.
```svelte
import { Stage, Layer, Rect } from 'svelte-konva';
function handleClick(e) {
const konvaEvent = e.detail;
window.alert(`Clicked on rectangle: ${konvaEvent.type}`);
}
```
### Accessing the underlying Konva node
In various cases it is useful and required to be able to access the underlying Konva node object. In svelte-konva you can do this by binding the `handle` prop.
```svelte
import { onMount, tick } from 'svelte';
import { Stage, Layer, Rect } from 'svelte-konva';
let rectangle;
onMount(async () => {
// Wait for dom update so the rectangle handle becomes defined
await tick();
const json = rectangle.toJSON();
window.alert(`Rectangle as JSON: ${json}`);
});
```
### Binding the config prop
By default svelte-konva keeps your config in sync (position, rotation, scale, etc.) with the Konva node after `dragend` and `transformend` events. If you bind the config prop any reactive blocks depending on the config will also be triggered once such changes happen. In case you don't want svelte-konva to sync those changes you can pass the `staticConfig` prop to the component.
```svelte
import { Stage, Layer, Rect } from 'svelte-konva';
let rectangleConfig = {
x: 100,
y: 100,
width: 400,
height: 200,
fill: 'blue',
draggable: true
};
$: console.log(
`Rectangle was dragged. New x: ${rectangleConfig.x}. New y: ${rectangleConfig.y}.`
);
```
### Usage with SvelteKit
Generally svelte-konva is a client-side only library. When using SvelteKit, special care needs to be taken if svelte-konva/Konva functionality is used on prerendered and server side rendered (SSR) components. Prerendering and SSR happens in a Node.js environment which causes Konva to require the [canvas](https://www.npmjs.com/package/canvas) library as Konva can also be used in Node.js environments. When you use svelte-konva in such conditions you'll likely run into the following error:
> Error: Cannot find module 'canvas'
There are multiple solutions to this problem:
**Installing canvas:**
Simplest solution is to install canvas:
```npm
npm i canvas
```
This will satisfy the canvas dependency of Konva and you can use svelte-konva components in prerendered and SSR SvelteKit pages. The solution is a bit messy though, as you now have installed a package you don't really need which adds unnecessary overhead. Alternatively use one of the following solutions:
**Dynamically import your svelte-konva stage:**
A better approach is to dynamically import your svelte-konva canvas on the client-side only. Suppose you have a Svelte component containing your stage with various svelte-konva components:
_MyCanvas.svelte_
```svelte
import { Stage, Layer, Rect } from 'svelte-konva';
import OtherComponentUsingSvelteKonva from './OtherComponentUsingSvelteKonva.svelte';
const rectangleConfig = {
/*...*/
};
```
To use this component inside a SvelteKit prerendered/SSR page you can dynamically import it inside `onMount()` and render it using ``:
_+page.svelte_
```svelte
import { onMount } from 'svelte';
// typescript:
// import type MyCanvasComponent from '$lib/MyCanvas.svelte';
let MyCanvas;
// typescript:
// let MyCanvas: typeof MyCanvasComponent;
onMount(async () => {
// Dynamically import your canvas component encapsulating all svelte-konva functionality inside onMount()
MyCanvas = (await import('$lib/MyCanvas.svelte')).default;
});
This is my fancy server side rendered (or prerendered) page.
```
**Dynamically import svelte-konva using vite:**
The [vite-plugin-iso-import](https://www.npmjs.com/package/vite-plugin-iso-import) allows you to make client-side only imports without needing the manual approach in `onMount()` described above. Please follow the installation instructions in the [README](https://www.npmjs.com/package/vite-plugin-iso-import) then you can dynamically import your component like so:
_+page.svelte_
```svelte
import MyCanvasComponent from '$lib/MyCanvas.svelte?client'; // Client-side only import
// Set component variable to null if page is rendered in SSR, otherwise use client-side only import
let MyCanvas = import.meta.env.SSR ? null : MyCanvasComponent;
This is my fancy server side rendered (or prerendered) page.
```
Currently vite-plugin-iso-import cannot automatically fix intellisense inside .svelte files with TypeScript. Consult the [README](https://www.npmjs.com/package/vite-plugin-iso-import) for a workaround to this problem.
For further examples please consult the [docs](https://konvajs.org/docs/svelte) or clone the repo and run `npm i && npm run examples`.
## Changelog
Please refer to the [CHANGELOG.md](https://github.com/konvajs/svelte-konva/blob/master/CHANGELOG.md) or [releases](https://github.com/konvajs/svelte-konva/releases) page.