0
# Shape Library
1

2
ZRender provides a comprehensive library of built-in geometric shapes, from basic primitives like circles and rectangles to complex shapes like stars and trochoids. All shapes inherit from the Path class and support complete styling, transformations, and event handling.
3

4
## Basic Shapes
5

6
### Circle
7

8
Perfect circles with center point and radius:
9

10
```typescript { .api }
11
class Circle extends Path {
12
  constructor(opts: CircleProps);
13
  shape: CircleShape;
14
}
15

16
interface CircleProps extends PathProps {
17
  shape: CircleShape;
18
}
19

20
interface CircleShape {
21
  cx: number;    // Center X coordinate
22
  cy: number;    // Center Y coordinate
23
  r: number;     // Radius
24
}
25
```
26

27
### Rect
28

29
Rectangles with optional rounded corners:
30

31
```typescript { .api }
32
class Rect extends Path {
33
  constructor(opts: RectProps);
34
  shape: RectShape;
35
}
36

37
interface RectProps extends PathProps {
38
  shape: RectShape;
39
}
40

41
interface RectShape {
42
  x: number;           // Top-left X coordinate
43
  y: number;           // Top-left Y coordinate
44
  width: number;       // Width
45
  height: number;      // Height
46
  r?: number | number[]; // Corner radius (single value or [TL, TR, BR, BL])
47
}
48
```
49

50
### Ellipse
51

52
Elliptical shapes with independent X and Y radii:
53

54
```typescript { .api }
55
class Ellipse extends Path {
56
  constructor(opts: EllipseProps);
57
  shape: EllipseShape;
58
}
59

60
interface EllipseProps extends PathProps {
61
  shape: EllipseShape;
62
}
63

64
interface EllipseShape {
65
  cx: number;    // Center X coordinate
66
  cy: number;    // Center Y coordinate
67
  rx: number;    // X-axis radius
68
  ry: number;    // Y-axis radius
69
}
70
```
71

72
## Linear Shapes
73

74
### Line
75

76
Straight line segments:
77

78
```typescript { .api }
79
class Line extends Path {
80
  constructor(opts: LineProps);
81
  shape: LineShape;
82
}
83

84
interface LineProps extends PathProps {
85
  shape: LineShape;
86
}
87

88
interface LineShape {
89
  x1: number;    // Start X coordinate
90
  y1: number;    // Start Y coordinate
91
  x2: number;    // End X coordinate
92
  y2: number;    // End Y coordinate
93
  percent?: number; // Line completion percentage (0-1)
94
}
95
```
96

97
### Polyline
98

99
Open multi-point line:
100

101
```typescript { .api }
102
class Polyline extends Path {
103
  constructor(opts: PolylineProps);
104
  shape: PolylineShape;
105
}
106

107
interface PolylineProps extends PathProps {
108
  shape: PolylineShape;
109
}
110

111
interface PolylineShape {
112
  points: number[][]; // Array of [x, y] coordinate pairs
113
  smooth?: number | 'spline' | 'bezier'; // Smoothing factor
114
}
115
```
116

117
### Polygon
118

119
Closed multi-point shape:
120

121
```typescript { .api }
122
class Polygon extends Path {
123
  constructor(opts: PolygonProps);
124
  shape: PolygonShape;
125
}
126

127
interface PolygonProps extends PathProps {
128
  shape: PolygonShape;
129
}
130

131
interface PolygonShape {
132
  points: number[][]; // Array of [x, y] coordinate pairs
133
  smooth?: number | 'spline' | 'bezier'; // Smoothing factor
134
}
135
```
136

137
## Curved Shapes
138

139
### Arc
140

141
Arc segments and sectors:
142

143
```typescript { .api }
144
class Arc extends Path {
145
  constructor(opts: ArcProps);
146
  shape: ArcShape;
147
}
148

149
interface ArcProps extends PathProps {
150
  shape: ArcShape;
151
}
152

153
interface ArcShape {
154
  cx: number;        // Center X coordinate
155
  cy: number;        // Center Y coordinate
156
  r: number;         // Radius
157
  startAngle: number; // Start angle in radians
158
  endAngle: number;   // End angle in radians
159
  clockwise?: boolean; // Direction of arc
160
}
161
```
162

163
### Sector
164

165
Pie chart sectors (arc with lines to center):
166

167
```typescript { .api }
168
class Sector extends Path {
169
  constructor(opts: SectorProps);
170
  shape: SectorShape;
171
}
172

173
interface SectorProps extends PathProps {
174
  shape: SectorShape;
175
}
176

177
interface SectorShape {
178
  cx: number;         // Center X coordinate
179
  cy: number;         // Center Y coordinate
180
  r0: number;         // Inner radius
181
  r: number;          // Outer radius
182
  startAngle: number; // Start angle in radians
183
  endAngle: number;   // End angle in radians
184
  clockwise?: boolean; // Direction of arc
185
}
186
```
187

188
### Ring
189

190
Donut or ring shapes:
191

192
```typescript { .api }
193
class Ring extends Path {
194
  constructor(opts: RingProps);
195
  shape: RingShape;
196
}
197

198
interface RingProps extends PathProps {
199
  shape: RingShape;
200
}
201

202
interface RingShape {
203
  cx: number;    // Center X coordinate
204
  cy: number;    // Center Y coordinate
205
  r: number;     // Outer radius
206
  r0: number;    // Inner radius
207
}
208
```
209

210
### BezierCurve
211

212
Cubic Bézier curves:
213

214
```typescript { .api }
215
class BezierCurve extends Path {
216
  constructor(opts: BezierCurveProps);
217
  shape: BezierCurveShape;
218
}
219

220
interface BezierCurveProps extends PathProps {
221
  shape: BezierCurveShape;
222
}
223

224
interface BezierCurveShape {
225
  x1: number;    // Start point X
226
  y1: number;    // Start point Y
227
  x2: number;    // End point X
228
  y2: number;    // End point Y
229
  cpx1: number;  // Control point 1 X
230
  cpy1: number;  // Control point 1 Y
231
  cpx2: number;  // Control point 2 X
232
  cpy2: number;  // Control point 2 Y
233
  percent?: number; // Curve completion percentage (0-1)
234
}
235
```
236

237
## Complex Shapes
238

239
### Star
240

241
Multi-pointed star shapes:
242

243
```typescript { .api }
244
class Star extends Path {
245
  constructor(opts: StarProps);
246
  shape: StarShape;
247
}
248

249
interface StarProps extends PathProps {
250
  shape: StarShape;
251
}
252

253
interface StarShape {
254
  cx: number;    // Center X coordinate
255
  cy: number;    // Center Y coordinate
256
  n: number;     // Number of points
257
  r0: number;    // Inner radius
258
  r: number;     // Outer radius
259
}
260
```
261

262
### Heart
263

264
Heart shape:
265

266
```typescript { .api }
267
class Heart extends Path {
268
  constructor(opts: HeartProps);
269
  shape: HeartShape;
270
}
271

272
interface HeartProps extends PathProps {
273
  shape: HeartShape;
274
}
275

276
interface HeartShape {
277
  cx: number;    // Center X coordinate
278
  cy: number;    // Center Y coordinate
279
  width: number; // Heart width
280
  height: number; // Heart height
281
}
282
```
283

284
### Droplet
285

286
Water droplet or teardrop shape:
287

288
```typescript { .api }
289
class Droplet extends Path {
290
  constructor(opts: DropletProps);
291
  shape: DropletShape;
292
}
293

294
interface DropletProps extends PathProps {
295
  shape: DropletShape;
296
}
297

298
interface DropletShape {
299
  cx: number;    // Center X coordinate
300
  cy: number;    // Center Y coordinate
301
  width: number; // Droplet width
302
  height: number; // Droplet height
303
}
304
```
305

306
### Isogon
307

308
Regular polygons (triangle, pentagon, hexagon, etc.):
309

310
```typescript { .api }
311
class Isogon extends Path {
312
  constructor(opts: IsogonProps);
313
  shape: IsogonShape;
314
}
315

316
interface IsogonProps extends PathProps {
317
  shape: IsogonShape;
318
}
319

320
interface IsogonShape {
321
  x: number;     // Center X coordinate
322
  y: number;     // Center Y coordinate
323
  r: number;     // Radius
324
  n: number;     // Number of sides
325
}
326
```
327

328
## Mathematical Curves
329

330
### Rose
331

332
Rose curves (mathematical curves):
333

334
```typescript { .api }
335
class Rose extends Path {
336
  constructor(opts: RoseProps);
337
  shape: RoseShape;
338
}
339

340
interface RoseProps extends PathProps {
341
  shape: RoseShape;
342
}
343

344
interface RoseShape {
345
  cx: number;    // Center X coordinate
346
  cy: number;    // Center Y coordinate
347
  r: number[];   // Radius array
348
  k: number;     // Rose parameter
349
  n: number;     // Number of petals
350
}
351
```
352

353
### Trochoid
354

355
Trochoid curves (cycloid variations):
356

357
```typescript { .api }
358
class Trochoid extends Path {
359
  constructor(opts: TrochoidProps);
360
  shape: TrochoidShape;
361
}
362

363
interface TrochoidProps extends PathProps {
364
  shape: TrochoidShape;
365
}
366

367
interface TrochoidShape {
368
  cx: number;    // Center X coordinate
369
  cy: number;    // Center Y coordinate
370
  r: number;     // Fixed circle radius
371
  r0: number;    // Rolling circle radius
372
  d: number;     // Point distance from center
373
  location?: string; // 'out' | 'in'
374
}
375
```
376

377
## Usage Examples
378

379
### Basic Shapes
380

381
```typescript
382
import { Circle, Rect, Line } from "zrender";
383

384
// Create a circle
385
const circle = new Circle({
386
  shape: { cx: 100, cy: 100, r: 50 },
387
  style: {
388
    fill: '#ff6b6b',
389
    stroke: '#d63031',
390
    lineWidth: 2
391
  }
392
});
393

394
// Create a rounded rectangle
395
const rect = new Rect({
396
  shape: { x: 200, y: 50, width: 120, height: 80, r: 10 },
397
  style: {
398
    fill: '#74b9ff',
399
    stroke: '#0984e3',
400
    lineWidth: 2
401
  }
402
});
403

404
// Create a line
405
const line = new Line({
406
  shape: { x1: 50, y1: 200, x2: 250, y2: 250 },
407
  style: {
408
    stroke: '#00b894',
409
    lineWidth: 3,
410
    lineCap: 'round'
411
  }
412
});
413

414
zr.add(circle);
415
zr.add(rect);
416
zr.add(line);
417
```
418

419
### Complex Shapes
420

421
```typescript
422
import { Star, Heart, Sector } from "zrender";
423

424
// Create a 5-pointed star
425
const star = new Star({
426
  shape: {
427
    cx: 150,
428
    cy: 150,
429
    n: 5,       // 5 points
430
    r0: 30,     // Inner radius
431
    r: 60       // Outer radius
432
  },
433
  style: {
434
    fill: '#fdcb6e',
435
    stroke: '#e17055',
436
    lineWidth: 2
437
  }
438
});
439

440
// Create a heart
441
const heart = new Heart({
442
  shape: {
443
    cx: 300,
444
    cy: 150,
445
    width: 80,
446
    height: 80
447
  },
448
  style: {
449
    fill: '#e84393',
450
    stroke: '#c0392b',
451
    lineWidth: 2
452
  }
453
});
454

455
// Create a pie sector
456
const sector = new Sector({
457
  shape: {
458
    cx: 150,
459
    cy: 300,
460
    r0: 20,     // Inner radius (donut hole)
461
    r: 80,      // Outer radius
462
    startAngle: 0,
463
    endAngle: Math.PI / 2  // 90 degrees
464
  },
465
  style: {
466
    fill: '#00cec9',
467
    stroke: '#00b894',
468
    lineWidth: 2
469
  }
470
});
471

472
zr.add(star);
473
zr.add(heart);
474
zr.add(sector);
475
```
476

477
### Polylines and Polygons
478

479
```typescript
480
import { Polyline, Polygon } from "zrender";
481

482
// Create a smooth polyline
483
const polyline = new Polyline({
484
  shape: {
485
    points: [
486
      [50, 200], [100, 150], [150, 180], 
487
      [200, 120], [250, 160], [300, 100]
488
    ],
489
    smooth: 0.3  // Smooth factor
490
  },
491
  style: {
492
    stroke: '#6c5ce7',
493
    lineWidth: 3,
494
    fill: 'none'
495
  }
496
});
497

498
// Create a polygon
499
const polygon = new Polygon({
500
  shape: {
501
    points: [
502
      [100, 300], [150, 250], [200, 280],
503
      [180, 320], [120, 330]
504
    ]
505
  },
506
  style: {
507
    fill: '#a29bfe',
508
    stroke: '#6c5ce7',
509
    lineWidth: 2
510
  }
511
});
512

513
zr.add(polyline);
514
zr.add(polygon);
515
```
516

517
### Animated Shapes
518

519
```typescript
520
import { Circle, Arc } from "zrender";
521

522
// Animated growing circle
523
const growingCircle = new Circle({
524
  shape: { cx: 200, cy: 200, r: 10 },
525
  style: { fill: '#00b894', opacity: 0.8 }
526
});
527

528
growingCircle.animate('shape')
529
  .when(2000, { r: 100 })
530
  .start('easeOutElastic');
531

532
// Animated arc (progress indicator)
533
const progressArc = new Arc({
534
  shape: {
535
    cx: 300,
536
    cy: 300,
537
    r: 50,
538
    startAngle: -Math.PI / 2,
539
    endAngle: -Math.PI / 2,  // Start at 0%
540
    clockwise: true
541
  },
542
  style: {
543
    stroke: '#74b9ff',
544
    lineWidth: 8,
545
    lineCap: 'round',
546
    fill: 'none'
547
  }
548
});
549

550
// Animate to 75% complete
551
progressArc.animate('shape')
552
  .when(3000, { endAngle: -Math.PI / 2 + Math.PI * 1.5 })
553
  .start('easeInOut');
554

555
zr.add(growingCircle);
556
zr.add(progressArc);
557
```
558

559
### Shape States and Interactions
560

561
```typescript
562
import { Rect } from "zrender";
563

564
const interactiveRect = new Rect({
565
  shape: { x: 100, y: 100, width: 100, height: 60, r: 5 },
566
  style: {
567
    fill: '#0984e3',
568
    stroke: '#74b9ff',
569
    lineWidth: 2
570
  }
571
});
572

573
// Add hover states
574
interactiveRect.on('mouseover', () => {
575
  interactiveRect.animate('style')
576
    .when(200, {
577
      fill: '#74b9ff',
578
      shadowBlur: 10,
579
      shadowColor: '#0984e3'
580
    })
581
    .start();
582
});
583

584
interactiveRect.on('mouseout', () => {
585
  interactiveRect.animate('style')
586
    .when(200, {
587
      fill: '#0984e3',
588
      shadowBlur: 0
589
    })
590
    .start();
591
});
592

593
// Add click interaction
594
interactiveRect.on('click', () => {
595
  interactiveRect.animate('shape')
596
    .when(300, { r: 20 })
597
    .when(600, { r: 5 })
598
    .start('easeInOutBounce');
599
});
600

601
zr.add(interactiveRect);
602
```