0
# React Konva
1

2
React Konva is a JavaScript library for drawing complex canvas graphics using React. It provides declarative and reactive bindings to the Konva Framework, enabling developers to create high-performance 2D canvas applications with familiar React components and patterns.
3

4
## Package Information
5

6
- **Package Name**: react-konva
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install react-konva konva --save`
10

11
## Core Imports
12

13
```typescript
14
import { Stage, Layer, Rect, Circle, Text, Group } from "react-konva";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { Stage, Layer, Rect, Circle, Text, Group } = require("react-konva");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import React, { useState } from 'react';
27
import { render } from 'react-dom';
28
import { Stage, Layer, Rect, Text } from 'react-konva';
29
import Konva from 'konva';
30

31
const ColoredRect = () => {
32
  const [color, setColor] = useState('green');
33

34
  const handleClick = () => {
35
    setColor(Konva.Util.getRandomColor());
36
  };
37

38
  return (
39
    <Rect
40
      x={20}
41
      y={20}
42
      width={50}
43
      height={50}
44
      fill={color}
45
      shadowBlur={5}
46
      onClick={handleClick}
47
    />
48
  );
49
};
50

51
const App = () => {
52
  return (
53
    <Stage width={window.innerWidth} height={window.innerHeight}>
54
      <Layer>
55
        <Text text="Try click on rect" />
56
        <ColoredRect />
57
      </Layer>
58
    </Stage>
59
  );
60
};
61

62
render(<App />, document.getElementById('root'));
63
```
64

65
## Architecture
66

67
React Konva is built around several key components:
68

69
- **React Reconciler Integration**: Uses react-reconciler to bridge React's virtual DOM with Konva's canvas nodes
70
- **Component Hierarchy**: Stage (root) → Layer → Shape components, following Konva's node structure
71
- **Event System**: Comprehensive event handling mapped from Konva events to React props (onClick, onDragMove, etc.)
72
- **Performance Optimization**: FastLayer for high-performance rendering, batched updates for canvas drawing
73
- **TypeScript Support**: Full type definitions with generic component interfaces
74
- **Ref Support**: Access to underlying Konva instances through React refs
75

76
## Capabilities
77

78
### Core Components
79

80
Foundation components for building canvas applications, including the root Stage container, organizational layers, and grouping mechanisms.
81

82
```typescript { .api }
83
// Root canvas container
84
var Stage: KonvaNodeComponent<Konva.Stage, StageProps>;
85

86
// Layer for organizing shapes
87
var Layer: KonvaNodeComponent<Konva.Layer, Konva.LayerConfig>;
88

89
// High-performance layer
90
var FastLayer: KonvaNodeComponent<Konva.FastLayer, Konva.LayerConfig>;
91

92
// Grouping container
93
var Group: KonvaNodeComponent<Konva.Group, Konva.GroupConfig>;
94

95
interface StageProps extends Konva.NodeConfig, KonvaNodeEvents {
96
  className?: string;
97
  role?: string;
98
  style?: React.CSSProperties;
99
  tabIndex?: number;
100
  title?: string;
101
}
102
```
103

104
[Core Components](./core-components.md)
105

106
### Shape Components
107

108
Complete set of 2D shape components for creating graphics, from basic primitives like rectangles and circles to complex shapes like paths and custom shapes.
109

110
```typescript { .api }
111
// Basic shapes
112
var Rect: KonvaNodeComponent<Konva.Rect, Konva.RectConfig>;
113
var Circle: KonvaNodeComponent<Konva.Circle, Konva.CircleConfig>;
114
var Ellipse: KonvaNodeComponent<Konva.Ellipse, Konva.EllipseConfig>;
115

116
// Text rendering
117
var Text: KonvaNodeComponent<Konva.Text, Konva.TextConfig>;
118
var TextPath: KonvaNodeComponent<Konva.TextPath, Konva.TextPathConfig>;
119

120
// Complex shapes
121
var Line: KonvaNodeComponent<Konva.Line, Konva.LineConfig>;
122
var Path: KonvaNodeComponent<Konva.Path, Konva.PathConfig>;
123
var Shape: KonvaNodeComponent<Konva.Shape, Konva.ShapeConfig>;
124
```
125

126
[Shape Components](./shapes.md)
127

128
### Event Handling and Interactions
129

130
Comprehensive event system supporting mouse, touch, pointer, and drag events with interactive transformation capabilities.
131

132
```typescript { .api }
133
interface KonvaNodeEvents {
134
  // Mouse events
135
  onMouseOver?(evt: Konva.KonvaEventObject<MouseEvent>): void;
136
  onMouseMove?(evt: Konva.KonvaEventObject<MouseEvent>): void;
137
  onClick?(evt: Konva.KonvaEventObject<MouseEvent>): void;
138
  
139
  // Touch events
140
  onTouchStart?(evt: Konva.KonvaEventObject<TouchEvent>): void;
141
  onTouchMove?(evt: Konva.KonvaEventObject<TouchEvent>): void;
142
  
143
  // Drag events
144
  onDragStart?(evt: Konva.KonvaEventObject<DragEvent>): void;
145
  onDragMove?(evt: Konva.KonvaEventObject<DragEvent>): void;
146
  onDragEnd?(evt: Konva.KonvaEventObject<DragEvent>): void;
147
}
148

149
// Interactive transformation component
150
var Transformer: KonvaNodeComponent<Konva.Transformer, Konva.TransformerConfig>;
151
```
152

153
[Event Handling and Interactions](./interactions.md)
154

155
### Utility Functions
156

157
Configuration and utility functions for customizing behavior, accessing the reconciler, and managing strict mode updates.
158

159
```typescript { .api }
160
// Strict mode configuration
161
var useStrictMode: (useStrictMode: boolean) => void;
162

163
// React reconciler instance
164
var KonvaRenderer: ReactReconciler.Reconciler<any, any, any, any, any, any>;
165

166
// Library version
167
var version: string;
168
```
169

170
[Utility Functions](./utilities.md)
171

172
## Types
173

174
```typescript { .api }
175
// Generic component interface for all Konva nodes
176
interface KonvaNodeComponent<
177
  Node extends Konva.Node,
178
  Props = Konva.NodeConfig
179
> extends React.FC<Props & KonvaNodeEvents & React.ClassAttributes<Node>> {
180
  getPublicInstance(): Node;
181
  getNativeNode(): Node;
182
}
183

184
// Comprehensive event interface
185
interface KonvaNodeEvents {
186
  // Mouse events
187
  onMouseOver?(evt: Konva.KonvaEventObject<MouseEvent>): void;
188
  onMouseMove?(evt: Konva.KonvaEventObject<MouseEvent>): void;
189
  onMouseOut?(evt: Konva.KonvaEventObject<MouseEvent>): void;
190
  onMouseEnter?(evt: Konva.KonvaEventObject<MouseEvent>): void;
191
  onMouseLeave?(evt: Konva.KonvaEventObject<MouseEvent>): void;
192
  onMouseDown?(evt: Konva.KonvaEventObject<MouseEvent>): void;
193
  onMouseUp?(evt: Konva.KonvaEventObject<MouseEvent>): void;
194
  onWheel?(evt: Konva.KonvaEventObject<WheelEvent>): void;
195
  onClick?(evt: Konva.KonvaEventObject<MouseEvent>): void;
196
  onDblClick?(evt: Konva.KonvaEventObject<MouseEvent>): void;
197
  
198
  // Touch events
199
  onTouchStart?(evt: Konva.KonvaEventObject<TouchEvent>): void;
200
  onTouchMove?(evt: Konva.KonvaEventObject<TouchEvent>): void;
201
  onTouchEnd?(evt: Konva.KonvaEventObject<TouchEvent>): void;
202
  onTap?(evt: Konva.KonvaEventObject<Event>): void;
203
  onDblTap?(evt: Konva.KonvaEventObject<Event>): void;
204
  
205
  // Drag events
206
  onDragStart?(evt: Konva.KonvaEventObject<DragEvent>): void;
207
  onDragMove?(evt: Konva.KonvaEventObject<DragEvent>): void;
208
  onDragEnd?(evt: Konva.KonvaEventObject<DragEvent>): void;
209
  
210
  // Transform events
211
  onTransform?(evt: Konva.KonvaEventObject<Event>): void;
212
  onTransformStart?(evt: Konva.KonvaEventObject<Event>): void;
213
  onTransformEnd?(evt: Konva.KonvaEventObject<Event>): void;
214
  
215
  // Pointer events
216
  onPointerDown?(evt: Konva.KonvaEventObject<PointerEvent>): void;
217
  onPointerMove?(evt: Konva.KonvaEventObject<PointerEvent>): void;
218
  onPointerUp?(evt: Konva.KonvaEventObject<PointerEvent>): void;
219
  onPointerCancel?(evt: Konva.KonvaEventObject<PointerEvent>): void;
220
  onPointerEnter?(evt: Konva.KonvaEventObject<PointerEvent>): void;
221
  onPointerLeave?(evt: Konva.KonvaEventObject<PointerEvent>): void;
222
  onPointerOver?(evt: Konva.KonvaEventObject<PointerEvent>): void;
223
  onPointerOut?(evt: Konva.KonvaEventObject<PointerEvent>): void;
224
  onPointerClick?(evt: Konva.KonvaEventObject<PointerEvent>): void;
225
  onPointerDblClick?(evt: Konva.KonvaEventObject<PointerEvent>): void;
226
  onGotPointerCapture?(evt: Konva.KonvaEventObject<PointerEvent>): void;
227
  onLostPointerCapture?(evt: Konva.KonvaEventObject<PointerEvent>): void;
228
  
229
  // Context menu
230
  onContextMenu?(evt: Konva.KonvaEventObject<PointerEvent>): void;
231
}
232

233
// Stage-specific props interface
234
interface StageProps extends Konva.NodeConfig, KonvaNodeEvents, Pick<
235
  React.HTMLAttributes<HTMLDivElement>,
236
  'className' | 'role' | 'style' | 'tabIndex' | 'title'
237
> {}
238
```