0
# Fill Objects and Styling
1

2
Advanced fill options including linear gradients, radial gradients, and image patterns for sophisticated graphics styling. These fill objects can be used with any Shape or shape component in place of solid colors.
3

4
## Capabilities
5

6
### LinearGradient
7

8
Creates linear gradient fills that transition colors along a straight line between two points.
9

10
```javascript { .api }
11
/**
12
 * Linear gradient fill object
13
 * Creates a gradient that transitions colors along a straight line
14
 * @param stops - Array of color stops defining the gradient
15
 * @param x1 - X coordinate of gradient start point
16
 * @param y1 - Y coordinate of gradient start point  
17
 * @param x2 - X coordinate of gradient end point
18
 * @param y2 - Y coordinate of gradient end point
19
 */
20
class LinearGradient {
21
  constructor(stops: ColorStop[], x1: number, y1: number, x2: number, y2: number);
22
  
23
  /**
24
   * Applies the gradient fill to an ART node
25
   * @param node - ART node to apply gradient to
26
   */
27
  applyFill(node: any): void;
28
}
29

30
// Color stop format for gradients
31
interface ColorStop {
32
  offset: number;  // Position along gradient (0-1)
33
  color: string;   // Color at this position
34
}
35
```
36

37
**Usage Examples:**
38

39
```javascript
40
import React from 'react';
41
import { Surface, Shape, Path, LinearGradient } from 'react-art';
42

43
// Basic linear gradient
44
function LinearGradientShape() {
45
  const path = Path()
46
    .moveTo(0, 0)
47
    .lineTo(100, 0)
48
    .lineTo(100, 100)
49
    .lineTo(0, 100)
50
    .close();
51

52
  // Horizontal gradient from left to right
53
  const gradient = new LinearGradient(
54
    [
55
      { offset: 0, color: '#ff0000' },    // Red at start
56
      { offset: 1, color: '#0000ff' }     // Blue at end
57
    ],
58
    0, 0,    // Start point (left)
59
    100, 0   // End point (right)
60
  );
61

62
  return (
63
    <Surface width={120} height={120}>
64
      <Shape d={path} fill={gradient} />
65
    </Surface>
66
  );
67
}
68

69
// Multi-color vertical gradient
70
function MultiColorGradient() {
71
  const path = Path()
72
    .moveTo(10, 10)
73
    .lineTo(90, 10)
74
    .lineTo(90, 90)
75
    .lineTo(10, 90)
76
    .close();
77

78
  const gradient = new LinearGradient(
79
    [
80
      { offset: 0, color: '#ff0000' },    // Red at top
81
      { offset: 0.5, color: '#00ff00' },  // Green in middle
82
      { offset: 1, color: '#0000ff' }     // Blue at bottom
83
    ],
84
    0, 10,   // Start point (top)
85
    0, 90    // End point (bottom)
86
  );
87

88
  return (
89
    <Surface width={100} height={100}>
90
      <Shape d={path} fill={gradient} />
91
    </Surface>
92
  );
93
}
94

95
// Diagonal gradient
96
function DiagonalGradient() {
97
  const path = Path()
98
    .moveTo(0, 0)
99
    .lineTo(80, 0)
100
    .lineTo(80, 80)
101
    .lineTo(0, 80)
102
    .close();
103

104
  const gradient = new LinearGradient(
105
    [
106
      { offset: 0, color: '#ffd700' },    // Gold
107
      { offset: 1, color: '#ff8c00' }     // Dark orange
108
    ],
109
    0, 0,     // Top-left
110
    80, 80    // Bottom-right
111
  );
112

113
  return (
114
    <Surface width={100} height={100}>
115
      <Shape d={path} fill={gradient} />
116
    </Surface>
117
  );
118
}
119
```
120

121
### RadialGradient
122

123
Creates radial gradient fills that transition colors in a circular pattern from a center point.
124

125
```javascript { .api }
126
/**
127
 * Radial gradient fill object
128
 * Creates a gradient that transitions colors in a circular pattern
129
 * @param stops - Array of color stops defining the gradient
130
 * @param fx - X coordinate of gradient focal point
131
 * @param fy - Y coordinate of gradient focal point
132
 * @param rx - X radius of the gradient ellipse
133
 * @param ry - Y radius of the gradient ellipse
134
 * @param cx - X coordinate of gradient center
135
 * @param cy - Y coordinate of gradient center
136
 */
137
class RadialGradient {
138
  constructor(stops: ColorStop[], fx: number, fy: number, rx: number, ry: number, cx: number, cy: number);
139
  
140
  /**
141
   * Applies the gradient fill to an ART node
142
   * @param node - ART node to apply gradient to
143
   */
144
  applyFill(node: any): void;
145
}
146
```
147

148
**Usage Examples:**
149

150
```javascript
151
import React from 'react';
152
import { Surface, Shape, Path, RadialGradient } from 'react-art';
153
import Circle from 'react-art/Circle';
154

155
// Basic radial gradient on circle
156
function RadialGradientCircle() {
157
  const gradient = new RadialGradient(
158
    [
159
      { offset: 0, color: '#ffffff' },    // White at center
160
      { offset: 1, color: '#000000' }     // Black at edge
161
    ],
162
    50, 50,   // Focal point (center)
163
    40, 40,   // X and Y radius
164
    50, 50    // Center point
165
  );
166

167
  return (
168
    <Surface width={100} height={100}>
169
      <Circle radius={40} fill={gradient} />
170
    </Surface>
171
  );
172
}
173

174
// Elliptical radial gradient
175
function EllipticalGradient() {
176
  const path = Path()
177
    .moveTo(10, 25)
178
    .lineTo(90, 25)
179
    .lineTo(90, 75)
180
    .lineTo(10, 75)
181
    .close();
182

183
  const gradient = new RadialGradient(
184
    [
185
      { offset: 0, color: '#ff69b4' },    // Hot pink
186
      { offset: 0.7, color: '#ff1493' },  // Deep pink
187
      { offset: 1, color: '#8b008b' }     // Dark magenta
188
    ],
189
    50, 50,   // Focal point
190
    30, 15,   // X radius (wide), Y radius (narrow) - creates ellipse
191
    50, 50    // Center point
192
  );
193

194
  return (
195
    <Surface width={100} height={100}>
196
      <Shape d={path} fill={gradient} />
197
    </Surface>
198
  );
199
}
200

201
// Off-center focal point
202
function OffCenterRadial() {
203
  const gradient = new RadialGradient(
204
    [
205
      { offset: 0, color: '#ffff00' },    // Yellow
206
      { offset: 1, color: '#ff0000' }     // Red
207
    ],
208
    30, 30,   // Focal point (off-center)
209
    50, 50,   // Radius
210
    50, 50    // Center point
211
  );
212

213
  return (
214
    <Surface width={100} height={100}>
215
      <Circle radius={45} fill={gradient} />
216
    </Surface>
217
  );
218
}
219
```
220

221
### Pattern
222

223
Creates image pattern fills that tile an image across the shape.
224

225
```javascript { .api }
226
/**
227
 * Image pattern fill object
228
 * Creates a fill that tiles an image across the shape
229
 * @param url - URL or data URI of the image to use as pattern
230
 * @param width - Width of each pattern tile
231
 * @param height - Height of each pattern tile
232
 * @param left - X offset of pattern origin
233
 * @param top - Y offset of pattern origin
234
 */
235
class Pattern {
236
  constructor(url: string, width: number, height: number, left: number, top: number);
237
  
238
  /**
239
   * Applies the pattern fill to an ART node
240
   * @param node - ART node to apply pattern to
241
   */
242
  applyFill(node: any): void;
243
}
244
```
245

246
**Usage Examples:**
247

248
```javascript
249
import React from 'react';
250
import { Surface, Shape, Path, Pattern } from 'react-art';
251
import Rectangle from 'react-art/Rectangle';
252

253
// Basic image pattern
254
function ImagePattern() {
255
  const pattern = new Pattern(
256
    'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==',
257
    20, 20,  // Tile size
258
    0, 0     // Offset
259
  );
260

261
  return (
262
    <Surface width={100} height={100}>
263
      <Rectangle width={80} height={80} fill={pattern} />
264
    </Surface>
265
  );
266
}
267

268
// Pattern with offset
269
function OffsetPattern() {
270
  const pattern = new Pattern(
271
    '/path/to/texture.png',
272
    30, 30,   // Tile size
273
    10, 10    // Offset (shifts pattern)
274
  );
275

276
  const path = Path()
277
    .moveTo(0, 0)
278
    .lineTo(100, 0)
279
    .lineTo(50, 100)
280
    .close();
281

282
  return (
283
    <Surface width={120} height={120}>
284
      <Shape d={path} fill={pattern} />
285
    </Surface>
286
  );
287
}
288

289
// Small repeating pattern
290
function RepeatingPattern() {
291
  // Create a small checkerboard pattern using data URI
292
  const checkerboard = new Pattern(
293
    'data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTAiIGhlaWdodD0iMTAiIHZpZXdCb3g9IjAgMCAxMCAxMCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHJlY3Qgd2lkdGg9IjUiIGhlaWdodD0iNSIgZmlsbD0iIzAwMCIvPgo8cmVjdCB4PSI1IiB5PSI1IiB3aWR0aD0iNSIgaGVpZ2h0PSI1IiBmaWxsPSIjMDAwIi8+Cjwvc3ZnPgo=',
294
    10, 10,   // Small tile size for tight pattern
295
    0, 0
296
  );
297

298
  return (
299
    <Surface width={100} height={100}>
300
      <Rectangle width={90} height={90} fill={checkerboard} />
301
    </Surface>
302
  );
303
}
304
```
305

306
## Fill Object Usage
307

308
### Using Fill Objects with Components
309

310
All fill objects can be used with any Shape or shape component by passing them to the `fill` prop:
311

312
```javascript
313
import { Surface, Shape, LinearGradient } from 'react-art';
314
import Circle from 'react-art/Circle';
315
import Rectangle from 'react-art/Rectangle';
316
import Wedge from 'react-art/Wedge';
317

318
function GradientShapes() {
319
  const gradient = new LinearGradient(
320
    [
321
      { offset: 0, color: '#ff0000' },
322
      { offset: 1, color: '#0000ff' }
323
    ],
324
    0, 0, 100, 0
325
  );
326

327
  return (
328
    <Surface width={300} height={100}>
329
      <Circle radius={30} fill={gradient} />
330
      <Rectangle width={60} height={60} fill={gradient} />
331
      <Wedge outerRadius={35} startAngle={0} endAngle={180} fill={gradient} />
332
    </Surface>
333
  );
334
}
335
```
336

337
### Combining with Strokes
338

339
Fill objects work alongside stroke properties:
340

341
```javascript
342
function StyledGradientShape() {
343
  const gradient = new RadialGradient(
344
    [
345
      { offset: 0, color: '#ffff00' },
346
      { offset: 1, color: '#ff8c00' }
347
    ],
348
    50, 50, 40, 40, 50, 50
349
  );
350

351
  return (
352
    <Surface width={100} height={100}>
353
      <Circle 
354
        radius={40} 
355
        fill={gradient}
356
        stroke="#333"
357
        strokeWidth={3}
358
      />
359
    </Surface>
360
  );
361
}
362
```
363

364
### Performance Considerations
365

366
- Gradients and patterns are more expensive to render than solid colors
367
- Complex gradients with many color stops can impact performance
368
- Pattern images should be optimized and appropriately sized
369
- Consider using CSS gradients for simple web-only gradients when possible
370

371
## Types
372

373
```javascript { .api }
374
// Color stop definition for gradients
375
interface ColorStop {
376
  /** Position along gradient (0 = start, 1 = end) */
377
  offset: number;
378
  /** Color value (hex, rgb, rgba, named colors) */
379
  color: string;
380
}
381

382
// Fill object union type
383
type FillObject = LinearGradient | RadialGradient | Pattern;
384

385
// Fill property type (used by Shape and shape components)
386
type Fill = string | FillObject;
387
```