react-konva - GitLite

KO | EN

gitlite — search

#javascript #hacktoberfest #ai #llm #golang #go #android #machine-learning #linux #docker #windows #awesome #cli #awesome-list

react-konva

(★ 6,400)

React + Canvas = Love. JavaScript library for drawing complex canvas graphics using React.

파일 탐색기

최종 버전 다운로드 (.zip)

- - release.yml
  - test.yml
- FUNDING.yml
- makeUpdates.ts
- ReactKonva.ts
- ReactKonvaCore.tsx
- ReactKonvaHostConfig.ts
- - html-fixture.tsx
  - konva-helpers.ts
  - mocking.ts
  - render.tsx
- 01-mounting.test.tsx
- 02-scheduler.test.tsx
- 03-suspense.test.tsx
- 04-strict-mode.test.tsx
- 05-roots-portals.test.tsx
- 06-sync-external-store.test.tsx
- 07-mobx-race.test.tsx
- 08-stage-destroy.test.tsx
- 09-event-handling.test.tsx
- 10-refs-lifecycle.test.tsx
- 11-ssr.mjs
- 12-memory.test.tsx
- 13-error-handling.test.tsx
- 15-design-decisions.test.tsx
- 16-scheduling-invariants.test.tsx
- 17-transformer-state-sync.test.tsx
.gitignore
.travis.yml
build.mjs
LICENSE
package.json
ReactKonvaCore.d.ts
README.md
tsconfig.json
vitest.config.ts

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<p align="center">
  <img src="https://konvajs.org/img/icon.png" alt="Konva logo" height="60" />
</p>

# React Konva

[![Financial Contributors on Open Collective](https://opencollective.com/konva/all/badge.svg?label=financial+contributors)](https://opencollective.com/konva)
[![npm version](https://badge.fury.io/js/react-konva.svg)](http://badge.fury.io/js/react-konva)
[![Build Status](https://github.com/konvajs/react-konva/actions/workflows/test.yml/badge.svg)](https://github.com/konvajs/react-konva/actions/workflows/test.yml)

React Konva provides declarative React components for the [Konva](https://konvajs.org/) 2D canvas scene graph. Use it to build design editors, whiteboards, diagrams, annotations, and other interactive graphics.

React Konva is MIT licensed. It supports Konva shapes and events. It does not support React Native.

- [React tutorial](https://konvajs.org/docs/react/index.html)
- [Live demos](https://konvajs.org/docs/sandbox.html)
- [Konva API](https://konvajs.org/api/Konva.html)
- [Star the project](https://github.com/konvajs/react-konva)

[![A Konva Transformer around a selected image](https://konvajs.org/assets/demos/image-resize-min.png)](https://konvajs.org/docs/react/Transformer.html)

## Install

React Konva 19 requires React and React DOM `^19.2.0`. For React 18, install the latest React Konva 18 release.

```bash
npm install react-konva konva
```

## Quick example

```javascript
import {useState} from 'react';
import {Stage, Layer, Rect} from 'react-konva';

export default function App() {
  const [color, setColor] = useState('#00a8e8');
  return (
    <Stage width={600} height={400}>
      <Layer>
        <Rect
          x={50} y={50} width={120} height={80}
          fill={color} draggable
          onClick={() => setColor(color === '#00a8e8' ? '#ff7a00' : '#00a8e8')}
        />
      </Layer>
    </Stage>
  );
}
```

To get more info about `Konva` you can read
[Konva Overview](https://konvajs.org/docs/overview.html).

`react-konva` follows the Konva API. Learn the Konva scene graph, properties, and events before you add framework-specific patterns.

## Core API

`react-konva` supports Konva shapes with the same names. Event props use React names such as `onClick`, `onTouchMove`, and `onDragEnd`.

### Getting reference to Konva objects

To get reference of `Konva` instance of a node you can use `ref` property.

```javascript
import React, { useEffect, useRef } from 'react';

const MyShape = () => {
  const circleRef = useRef();

useEffect(() => {
    // log Konva.Circle instance
    console.log(circleRef.current);
  }, []);

return <Circle ref={circleRef} radius={50} fill="black" />;
};
```

### Strict mode

By default `react-konva` works in "non-strict" mode. If you changed a property **manually** (or by user action like `drag&drop`) properties of the node will be not matched with properties from `render()`. `react-konva` updates ONLY properties changed in `render()`.

In strict mode `react-konva` will update all properties of the nodes to the values that you provided in `render()` function, no matter changed they or not.

You should decide what mode is better in your actual use case.

To enable strict mode globally you can do this:

```javascript
import { useStrictMode } from 'react-konva';

useStrictMode(true);
```

Or you can enable it only for some components:

```javascript
<Rect width={50} height={50} fill="black" _useStrictMode />
```

Take a look into this example:

```javascript
import { Circle } from 'react-konva';
import Konva from 'konva';

const Shape = () => {
  const [color, setColor] = React.useState();

return (
    <Circle
      x={0}
      y={0}
      draggable
      radius={50}
      fill={color}
      onDragEnd={() => {
        setColor(Konva.Util.getRandomColor());
      }}
    />
  );
};
```

The circle is `draggable` and it changes its color on `dragend` event. In `strict` mode position of the node will be reset back to `{x: 0, y: 0}` (as we defined in render). But in `non-strict` mode the circle will keep its position, because `x` and `y` are not changed in render.

### Minimal bundle

By default `react-konva` imports full `Konva` version. With all the shapes and all filters. To minimize bundle size you can use minimal core version of `react-konva`:

```javascript
// load minimal version of 'react-konva`
import { Stage, Layer, Rect } from 'react-konva/lib/ReactKonvaCore';

// minimal version has NO support for core shapes and filters
// if you want import a shape into Konva namespace you can just do this:
import 'konva/lib/shapes/Rect';
```

Demo: [https://codesandbox.io/s/6l97wny44z](https://codesandbox.io/s/6l97wny44z)

## Usage with Next.js

**From `konva@10.0.0`, you don't need to do any extra steps. It will work out-of-the-box.**

If you use konva verion <= 9, continue reading.

Note: `react-konva` is designed to work in the client-side. On the server side, it will render just empty div. So it doesn't make much sense to use react-konva for server-side rendering. In Next.js you may have issue like

> Module not found: Can't resolve 'canvas'

Why do we see this error? `canvas` module is used for canvas rendering in Node.JS environment. `konva` library will use it there, but it doesn't have this dependency explicitly.

How to solve this issue? There are two approaches:

### Approach 1: manually install canvas module

You can install `canvas` module manually.

```bash
npm install canvas@next
```

The solution will solve the issue, but it will have unnecessary dependency on `canvas` module which may increase build time a little bit.

### Approach 2: Use dynamic import

Next.js docs: https://nextjs.org/docs/pages/building-your-application/optimizing/lazy-loading

With this approach your canvas component will be loaded on the client-side only. So you will not have any issues with server-side rendering. Also `next.js` will automatically understand that it doesn't need to load `canvas` module, because it is used for server-side rendering only.

#### Step 1 - Create canvas component

You need to define your canvas components somewhere in your `components` folder.

**It must be placed outside of `pages` or `app` folder (because they are used for server rendering).**

Your `components/canvas.js` file may look like this:

```js
import { Stage, Layer, Circle } from 'react-konva';

function Canvas(props) {
  return (
    <Stage width={window.innerWidth} height={window.innerHeight}>
      <Layer>
        <Circle x={200} y={100} radius={50} fill="green" />
      </Layer>
    </Stage>
  );
}

export default Canvas;
```

#### Step 2 - Use dynamic import

Then you can use it in your page. Notice, it is imported to have `'use client';`.

```js
'use client';
import dynamic from 'next/dynamic';

const Canvas = dynamic(() => import('../components/canvas'), {
  ssr: false,
});

export default function Page(props) {
  return <Canvas />;
}
```

#### Step 3 - Setup next.config.js

1. In some versions of next.js you may need to set up `next.config.js` to make it work:

```js
/** @type {import('next').NextConfig} */
const nextConfig = {
  webpack: (config) => {
    config.externals = [...config.externals, { canvas: 'canvas' }]; // required to make Konva & react-konva work
    return config;
  },
};

module.exports = nextConfig;
```

If you are using `turbopack` you may need to use this configuration:

```js
/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    turbo: {
      resolveAlias: {
        canvas: './empty.js',
      },
    },
  },
};

module.exports = nextConfig;
```

Also create empty file `empty.js` in the root of your project. That file will be used as replacement for `canvas` library. As we don't really need to use it, it will be just empty file.

### Usage with React Context

**Note: this section may be not relevant, because this issue was fixed in `react-konva@18.2.2`. So context should work by default.**

Due to a [known issue](https://github.com/facebook/react/issues/13336) with React, Contexts are not accessible by children of the react-konva `Stage` component. If you need to subscribe to a context from within the `Stage`, you need to "bridge" the context by creating a `Provider` as a child of the `Stage`. For more info, see [this discussion](https://github.com/konvajs/react-konva/issues/188#issuecomment-478302062) and this [react-redux demo](https://github.com/konvajs/react-konva/issues/311#issuecomment-454411007). Here is an example of bridging the context ([live demo](https://codesandbox.io/s/ykqw8r4r21)):

```js
import React, { Component } from 'react';
import Konva from 'konva';
import { render } from 'react-dom';
import { Stage, Layer, Rect } from 'react-konva';

const ThemeContext = React.createContext('red');

const ThemedRect = () => {
  const value = React.useContext(ThemeContext);
  return <Rect x={20} y={50} width={100} height={100} fill={value} shadowBlur={10} />;
};

const Canvas = () => {
  return (
    <ThemeContext.Consumer>
      {(value) => (
        <Stage width={window.innerWidth} height={window.innerHeight}>
          <ThemeContext.Provider value={value}>
            <Layer>
              <ThemedRect />
            </Layer>
          </ThemeContext.Provider>
        </Stage>
      )}
    </ThemeContext.Consumer>
  );
};

class App extends Component {
  render() {
    return (
      <ThemeContext.Provider value="blue">
        <Canvas />
      </ThemeContext.Provider>
    );
  }
}
```

## Comparisons

### react-konva vs react-canvas

[react-canvas](https://github.com/Flipboard/react-canvas) is a completely
different react plugin. It allows you to draw DOM-like objects (images, texts)
on canvas element in very performant way. It is NOT about drawing graphics, but
react-konva is exactly for drawing complex graphics on `<canvas>` element from
React.

### react-konva vs react-art

[react-art](https://github.com/reactjs/react-art) allows you to draw graphics on
a page. It also supports SVG for output. But it has no support of events of
shapes.

### react-konva vs vanilla canvas

Vanilla canvas is faster because when you use `react-konva` you have two layers of abstractions. Konva framework is on top of canvas and React is on top of Konva.
Depending on the use case this approach can be slow.
The purpose of `react-konva` is to reduce the complexity of the application and use well-known declarative way for drawing on canvas.

## [CHANGELOG](https://github.com/konvajs/react-konva/releases)

See the [Konva demos](https://konvajs.org/docs/sandbox.html) for more complete examples.