0
# Core Components
1

2
Foundation components for building canvas applications. These components provide the essential container hierarchy for organizing and managing canvas content with React Konva.
3

4
## Capabilities
5

6
### Stage Component
7

8
The root canvas container component that creates the HTML5 canvas element and initializes the Konva stage. This is the top-level component that must wrap all other React Konva components.
9

10
```typescript { .api }
11
/**
12
 * Root canvas container component
13
 * Creates HTML5 canvas element and Konva stage
14
 */
15
var Stage: KonvaNodeComponent<Konva.Stage, StageProps>;
16

17
interface StageProps extends Konva.NodeConfig, KonvaNodeEvents, Pick<
18
  React.HTMLAttributes<HTMLDivElement>,
19
  'className' | 'role' | 'style' | 'tabIndex' | 'title'
20
> {}
21
```
22

23
**Usage Examples:**
24

25
```typescript
26
import React from 'react';
27
import { Stage, Layer } from 'react-konva';
28

29
// Basic stage setup
30
const App = () => {
31
  return (
32
    <Stage width={800} height={600}>
33
      <Layer>
34
        {/* Shape components go here */}
35
      </Layer>
36
    </Stage>
37
  );
38
};
39

40
// Stage with HTML attributes and styling
41
const StyledApp = () => {
42
  return (
43
    <Stage 
44
      width={800} 
45
      height={600}
46
      className="canvas-container"
47
      style={{ border: '1px solid #ccc' }}
48
      tabIndex={0}
49
    >
50
      <Layer>
51
        {/* Shape components go here */}
52
      </Layer>
53
    </Stage>
54
  );
55
};
56

57
// Stage with event handling
58
const InteractiveApp = () => {
59
  const handleStageClick = (e) => {
60
    console.log('Stage clicked at:', e.target.getStage().getPointerPosition());
61
  };
62

63
  return (
64
    <Stage width={800} height={600} onClick={handleStageClick}>
65
      <Layer>
66
        {/* Shape components go here */}
67
      </Layer>
68
    </Stage>
69
  );
70
};
71
```
72

73
### Layer Component
74

75
Canvas layer component for organizing shapes into logical groups. Layers provide performance optimization by allowing selective redrawing and are essential containers for shape components.
76

77
```typescript { .api }
78
/**
79
 * Canvas layer component for organizing shapes
80
 * Provides performance optimization through selective redrawing
81
 */
82
var Layer: KonvaNodeComponent<Konva.Layer, Konva.LayerConfig>;
83
```
84

85
**Usage Examples:**
86

87
```typescript
88
import React from 'react';
89
import { Stage, Layer, Rect, Circle } from 'react-konva';
90

91
// Multiple layers for organization
92
const LayeredApp = () => {
93
  return (
94
    <Stage width={800} height={600}>
95
      <Layer name="background">
96
        <Rect width={800} height={600} fill="lightblue" />
97
      </Layer>
98
      <Layer name="shapes">
99
        <Circle x={100} y={100} radius={50} fill="red" />
100
        <Rect x={200} y={50} width={100} height={100} fill="green" />
101
      </Layer>
102
      <Layer name="ui">
103
        {/* UI elements that need frequent updates */}
104
      </Layer>
105
    </Stage>
106
  );
107
};
108

109
// Layer with opacity and visibility
110
const ConditionalLayer = () => {
111
  const [showLayer, setShowLayer] = React.useState(true);
112
  
113
  return (
114
    <Stage width={800} height={600}>
115
      <Layer visible={showLayer} opacity={0.8}>
116
        <Circle x={100} y={100} radius={50} fill="blue" />
117
      </Layer>
118
    </Stage>
119
  );
120
};
121
```
122

123
### FastLayer Component
124

125
High-performance layer component optimized for scenarios with many shapes or frequent updates. FastLayer sacrifices some features for better rendering performance.
126

127
```typescript { .api }
128
/**
129
 * High-performance layer component
130
 * Optimized for scenarios with many shapes or frequent updates
131
 */
132
var FastLayer: KonvaNodeComponent<Konva.FastLayer, Konva.LayerConfig>;
133
```
134

135
**Usage Examples:**
136

137
```typescript
138
import React from 'react';
139
import { Stage, FastLayer, Circle } from 'react-konva';
140

141
// FastLayer for many animated objects
142
const PerformantAnimation = () => {
143
  const [circles, setCircles] = React.useState([]);
144

145
  React.useEffect(() => {
146
    // Generate many circles for performance testing
147
    const newCircles = Array.from({ length: 1000 }, (_, i) => ({
148
      id: i,
149
      x: Math.random() * 800,
150
      y: Math.random() * 600,
151
      radius: Math.random() * 20 + 5,
152
      color: `hsl(${Math.random() * 360}, 50%, 50%)`
153
    }));
154
    setCircles(newCircles);
155
  }, []);
156

157
  return (
158
    <Stage width={800} height={600}>
159
      <FastLayer>
160
        {circles.map(circle => (
161
          <Circle
162
            key={circle.id}
163
            x={circle.x}
164
            y={circle.y}
165
            radius={circle.radius}
166
            fill={circle.color}
167
          />
168
        ))}
169
      </FastLayer>
170
    </Stage>
171
  );
172
};
173
```
174

175
### Group Component
176

177
Grouping container component for organizing shapes into logical collections. Groups can be transformed, styled, and managed as single units while maintaining individual shape properties.
178

179
```typescript { .api }
180
/**
181
 * Grouping container for organizing shapes into logical collections
182
 * Allows collective transformation and management of multiple shapes
183
 */
184
var Group: KonvaNodeComponent<Konva.Group, Konva.GroupConfig>;
185
```
186

187
**Usage Examples:**
188

189
```typescript
190
import React from 'react';
191
import { Stage, Layer, Group, Rect, Circle, Text } from 'react-konva';
192

193
// Basic grouping
194
const GroupedShapes = () => {
195
  return (
196
    <Stage width={800} height={600}>
197
      <Layer>
198
        <Group x={100} y={100} draggable>
199
          <Rect width={100} height={100} fill="red" />
200
          <Circle x={50} y={50} radius={25} fill="blue" />
201
          <Text x={10} y={110} text="Grouped Items" fontSize={14} />
202
        </Group>
203
      </Layer>
204
    </Stage>
205
  );
206
};
207

208
// Group with transformations
209
const TransformedGroup = () => {
210
  const [rotation, setRotation] = React.useState(0);
211

212
  React.useEffect(() => {
213
    const interval = setInterval(() => {
214
      setRotation(prev => prev + 1);
215
    }, 50);
216
    return () => clearInterval(interval);
217
  }, []);
218

219
  return (
220
    <Stage width={800} height={600}>
221
      <Layer>
222
        <Group 
223
          x={400} 
224
          y={300} 
225
          rotation={rotation}
226
          offsetX={50}
227
          offsetY={50}
228
        >
229
          <Rect x={0} y={0} width={100} height={100} fill="green" />
230
          <Circle x={50} y={50} radius={30} fill="yellow" />
231
        </Group>
232
      </Layer>
233
    </Stage>
234
  );
235
};
236

237
// Nested groups
238
const NestedGroups = () => {
239
  return (
240
    <Stage width={800} height={600}>
241
      <Layer>
242
        <Group x={50} y={50} name="main-group">
243
          <Group x={0} y={0} name="sub-group-1">
244
            <Rect width={50} height={50} fill="red" />
245
            <Circle x={25} y={25} radius={10} fill="white" />
246
          </Group>
247
          <Group x={100} y={0} name="sub-group-2">
248
            <Rect width={50} height={50} fill="blue" />
249
            <Circle x={25} y={25} radius={10} fill="white" />
250
          </Group>
251
        </Group>
252
      </Layer>
253
    </Stage>
254
  );
255
};
256
```
257

258
### Label Component
259

260
Label container component for creating labeled elements, typically used in combination with Tag and Text components for callouts, tooltips, and annotations.
261

262
```typescript { .api }
263
/**
264
 * Label container for creating labeled elements
265
 * Typically used with Tag and Text components for callouts and annotations
266
 */
267
var Label: KonvaNodeComponent<Konva.Label, Konva.LabelConfig>;
268
```
269

270
**Usage Examples:**
271

272
```typescript
273
import React from 'react';
274
import { Stage, Layer, Label, Tag, Text, Circle } from 'react-konva';
275

276
// Label with tag and text
277
const LabelExample = () => {
278
  return (
279
    <Stage width={800} height={600}>
280
      <Layer>
281
        <Circle x={200} y={200} radius={50} fill="red" />
282
        
283
        <Label x={200} y={120}>
284
          <Tag
285
            fill="black"
286
            pointerDirection="down"
287
            pointerWidth={10}
288
            pointerHeight={10}
289
            lineJoin="round"
290
            shadowColor="black"
291
            shadowBlur={10}
292
            shadowOffsetX={3}
293
            shadowOffsetY={3}
294
            shadowOpacity={0.3}
295
          />
296
          <Text
297
            text="This is a circle"
298
            fontFamily="Calibri"
299
            fontSize={18}
300
            padding={5}
301
            fill="white"
302
          />
303
        </Label>
304
      </Layer>
305
    </Stage>
306
  );
307
};
308

309
// Interactive tooltip label
310
const TooltipLabel = () => {
311
  const [showTooltip, setShowTooltip] = React.useState(false);
312
  const [tooltipPos, setTooltipPos] = React.useState({ x: 0, y: 0 });
313

314
  const handleMouseEnter = (e) => {
315
    setShowTooltip(true);
316
    setTooltipPos({
317
      x: e.target.x(),
318
      y: e.target.y() - 60
319
    });
320
  };
321

322
  return (
323
    <Stage width={800} height={600}>
324
      <Layer>
325
        <Circle 
326
          x={200} 
327
          y={200} 
328
          radius={50} 
329
          fill="blue"
330
          onMouseEnter={handleMouseEnter}
331
          onMouseLeave={() => setShowTooltip(false)}
332
        />
333
        
334
        {showTooltip && (
335
          <Label x={tooltipPos.x} y={tooltipPos.y}>
336
            <Tag fill="yellow" cornerRadius={5} />
337
            <Text text="Hover tooltip" fontSize={14} padding={5} />
338
          </Label>
339
        )}
340
      </Layer>
341
    </Stage>
342
  );
343
};
344
```