0
# Container Elements
1

2
Container elements for organizing, structuring, and reusing SVG content including the root SVG element, groups, definitions, and symbols.
3

4
## Capabilities
5

6
### Svg
7

8
Root SVG container element that establishes the SVG coordinate system and viewport.
9

10
```typescript { .api }
11
/**
12
 * Root SVG container element
13
 * @param width - Width of the SVG viewport
14
 * @param height - Height of the SVG viewport
15
 * @param viewBox - Viewport coordinates and dimensions "minX minY width height"
16
 * @param preserveAspectRatio - How to scale the viewBox content
17
 * @param color - Current color for child elements
18
 * @param title - Accessible title for the SVG
19
 */
20
interface SvgProps extends GProps, ViewProps, HitSlop {
21
  width?: NumberProp;
22
  height?: NumberProp;
23
  viewBox?: string;
24
  preserveAspectRatio?: string;
25
  color?: ColorValue;
26
  title?: string;
27
}
28

29
declare const Svg: React.ComponentType<SvgProps>;
30
```
31

32
**Usage Examples:**
33

34
```typescript
35
import Svg, { Circle } from "react-native-svg";
36

37
// Basic SVG container
38
<Svg width="100" height="100">
39
  <Circle cx="50" cy="50" r="40" fill="blue" />
40
</Svg>
41

42
// SVG with viewBox for scalable graphics
43
<Svg width="200" height="100" viewBox="0 0 100 50">
44
  <Circle cx="25" cy="25" r="20" fill="red" />
45
</Svg>
46

47
// SVG with aspect ratio preservation
48
<Svg
49
  width="200"
50
  height="100"
51
  viewBox="0 0 100 100"
52
  preserveAspectRatio="xMidYMid meet"
53
>
54
  <Circle cx="50" cy="50" r="40" fill="green" />
55
</Svg>
56
```
57

58
### G (Group)
59

60
Groups elements together for collective transformations, styling, and organization.
61

62
```typescript { .api }
63
/**
64
 * Groups SVG elements for collective styling and transformation
65
 * @param opacity - Opacity applied to entire group
66
 */
67
interface GProps extends CommonPathProps {
68
  opacity?: NumberProp;
69
}
70

71
declare const G: React.ComponentType<GProps>;
72
```
73

74
**Usage Examples:**
75

76
```typescript
77
import Svg, { G, Circle, Rect } from "react-native-svg";
78

79
// Basic grouping
80
<Svg width="200" height="100">
81
  <G fill="blue" stroke="black" strokeWidth="2">
82
    <Circle cx="50" cy="50" r="30" />
83
    <Rect x="100" y="20" width="60" height="60" />
84
  </G>
85
</Svg>
86

87
// Group with transformation
88
<Svg width="200" height="200">
89
  <G transform="translate(100,100) rotate(45)">
90
    <Rect x="-25" y="-25" width="50" height="50" fill="red" />
91
    <Circle cx="0" cy="0" r="5" fill="white" />
92
  </G>
93
</Svg>
94

95
// Nested groups with different styles
96
<Svg width="300" height="200">
97
  <G fill="lightblue" stroke="blue">
98
    <Circle cx="50" cy="50" r="30" />
99
    <G fill="lightgreen" stroke="green" transform="translate(100,0)">
100
      <Circle cx="50" cy="50" r="30" />
101
      <G fill="pink" stroke="red" transform="translate(100,0)">
102
        <Circle cx="50" cy="50" r="30" />
103
      </G>
104
    </G>
105
  </G>
106
</Svg>
107
```
108

109
### Defs
110

111
Container for reusable SVG elements that are not directly rendered but can be referenced by other elements.
112

113
```typescript { .api }
114
/**
115
 * Container for reusable SVG element definitions
116
 * Elements defined within Defs are not rendered but can be referenced by other elements
117
 */
118
interface DefsProps {
119
  children?: React.ReactNode;  
120
}
121

122
declare const Defs: React.ComponentType<DefsProps>;
123
```
124

125
**Usage Examples:**
126

127
```typescript
128
import Svg, { Defs, LinearGradient, Stop, Circle, ClipPath, Rect } from "react-native-svg";
129

130
// Gradient definitions
131
<Svg width="200" height="100">
132
  <Defs>
133
    <LinearGradient id="grad1" x1="0%" y1="0%" x2="100%" y2="0%">
134
      <Stop offset="0%" stopColor="red" />
135
      <Stop offset="100%" stopColor="blue" />
136
    </LinearGradient>
137
  </Defs>
138
  <Circle cx="50" cy="50" r="40" fill="url(#grad1)" />
139
</Svg>
140

141
// Clipping path definitions
142
<Svg width="200" height="100">
143
  <Defs>
144
    <ClipPath id="clip1">
145
      <Circle cx="50" cy="50" r="35" />
146
    </ClipPath>
147
  </Defs>
148
  <Rect x="10" y="10" width="80" height="80" fill="green" clipPath="url(#clip1)" />
149
</Svg>
150
```
151

152
### Symbol
153

154
Reusable graphic element with its own coordinate system that can be instantiated with Use elements.
155

156
```typescript { .api }
157
/**
158
 * Reusable symbol definition with its own coordinate system
159
 * @param id - Unique identifier for referencing
160
 * @param viewBox - Internal coordinate system "minX minY width height"
161
 * @param preserveAspectRatio - How to scale the symbol content
162
 */
163
interface SymbolProps extends CommonPathProps {
164
  id?: string;
165
  viewBox?: string;
166
  preserveAspectRatio?: string;
167
}
168

169
declare const Symbol: React.ComponentType<SymbolProps>;
170
```
171

172
**Usage Examples:**
173

174
```typescript
175
import Svg, { Defs, Symbol, Circle, Rect, Use } from "react-native-svg";
176

177
// Define and use symbols
178
<Svg width="300" height="200">
179
  <Defs>
180
    <Symbol id="icon" viewBox="0 0 50 50">
181
      <Circle cx="25" cy="25" r="20" fill="blue" />
182
      <Rect x="20" y="20" width="10" height="10" fill="white" />
183
    </Symbol>
184
  </Defs>
185
  
186
  <Use href="#icon" x="10" y="10" width="50" height="50" />
187
  <Use href="#icon" x="80" y="10" width="30" height="30" />
188
  <Use href="#icon" x="130" y="10" width="70" height="70" />
189
</Svg>
190
```
191

192
### Use
193

194
References and renders other SVG elements, enabling reuse and instantiation of symbols.
195

196
```typescript { .api }
197
/**
198
 * References and renders other SVG elements
199
 * @param href - Reference to element ID (e.g., "#symbolId")
200
 * @param x - X coordinate for rendering
201
 * @param y - Y coordinate for rendering  
202
 * @param width - Width override for symbols
203
 * @param height - Height override for symbols
204
 * @param opacity - Opacity of the referenced element
205
 */
206
interface UseProps extends CommonPathProps {
207
  href?: string;
208
  x?: NumberProp;
209
  y?: NumberProp;
210
  width?: NumberProp;
211
  height?: NumberProp;
212
  opacity?: NumberProp;
213
}
214

215
declare const Use: React.ComponentType<UseProps>;
216
```
217

218
**Usage Examples:**
219

220
```typescript
221
import Svg, { Defs, G, Circle, Use } from "react-native-svg";
222

223
// Reuse a group
224
<Svg width="300" height="200">
225
  <Defs>
226
    <G id="pattern">
227
      <Circle cx="0" cy="0" r="10" fill="red" />
228
      <Circle cx="20" cy="0" r="10" fill="blue" />
229
    </G>
230
  </Defs>
231
  
232
  <Use href="#pattern" x="50" y="50" />
233
  <Use href="#pattern" x="100" y="80" />
234
  <Use href="#pattern" x="150" y="110" />
235
</Svg>
236

237
// Use with transformations
238
<Svg width="200" height="200">
239
  <Defs>
240
    <Circle id="dot" cx="0" cy="0" r="5" fill="green" />
241
  </Defs>
242
  
243
  <Use href="#dot" x="50" y="50" />
244
  <Use href="#dot" x="100" y="50" transform="scale(2)" />
245
  <Use href="#dot" x="50" y="100" transform="rotate(45)" />
246
</Svg>
247
```
248

249
### ForeignObject
250

251
Embeds non-SVG content within an SVG, such as HTML elements or React Native views.
252

253
```typescript { .api }
254
/**
255
 * Embeds foreign content within SVG
256
 * @param x - X coordinate of foreign object
257
 * @param y - Y coordinate of foreign object
258
 * @param width - Width of foreign object area
259
 * @param height - Height of foreign object area
260
 */
261
interface ForeignObjectProps extends CommonPathProps {
262
  x?: NumberProp;
263
  y?: NumberProp;
264
  width?: NumberProp;
265
  height?: NumberProp;
266
}
267

268
declare const ForeignObject: React.ComponentType<ForeignObjectProps>;
269
```
270

271
**Usage Examples:**
272

273
```typescript
274
import React from "react";
275
import { Text, View } from "react-native";
276
import Svg, { ForeignObject, Circle } from "react-native-svg";
277

278
// Embed React Native components
279
<Svg width="200" height="200">
280
  <Circle cx="100" cy="100" r="90" fill="lightblue" stroke="blue" strokeWidth="2" />
281
  <ForeignObject x="50" y="80" width="100" height="40">
282
    <View style={{ backgroundColor: 'white', padding: 10, borderRadius: 5 }}>
283
      <Text style={{ textAlign: 'center' }}>React Native View</Text>
284
    </View>
285
  </ForeignObject>
286
</Svg>
287
```
288

289
### Image
290

291
Embeds raster images (PNG, JPEG, etc.) within SVG content with support for scaling and aspect ratio preservation.
292

293
```typescript { .api }
294
/**
295
 * Embeds raster images within SVG
296
 * @param x - X coordinate of image
297
 * @param y - Y coordinate of image
298
 * @param width - Width of image display area
299
 * @param height - Height of image display area
300
 * @param href - Image source (URI string or React Native source object)
301
 * @param xlinkHref - Legacy href attribute (deprecated, use href)
302
 * @param preserveAspectRatio - How to scale and position image within display area
303
 * @param opacity - Image opacity
304
 * @param onLoad - Callback when image loads successfully
305
 */
306
interface ImageProps extends CommonPathProps {
307
  x?: NumberProp;
308
  y?: NumberProp;
309
  width?: NumberProp;
310
  height?: NumberProp;
311
  href?: ImageSource | string;
312
  xlinkHref?: ImageSource | string; // deprecated
313
  preserveAspectRatio?: string;
314
  opacity?: NumberProp;
315
  onLoad?: (e: NativeSyntheticEvent<ImageLoadEventData>) => void;
316
}
317

318
declare const Image: React.ComponentType<ImageProps>;
319
```
320

321
**Usage Examples:**
322

323
```typescript
324
import Svg, { Image } from "react-native-svg";
325

326
// Image from URI
327
<Svg width="200" height="200">
328
  <Image
329
    x="10"
330
    y="10"
331
    width="180"
332
    height="180"
333
    href="https://example.com/image.png"
334
    preserveAspectRatio="xMidYMid meet"
335
  />
336
</Svg>
337

338
// Image from React Native asset
339
import logo from "./assets/logo.png";
340

341
<Svg width="150" height="100">
342
  <Image
343
    x="25"
344
    y="25"
345
    width="100"
346
    height="50"
347
    href={logo}
348
    opacity="0.8"
349
    onLoad={() => console.log("Image loaded")}
350
  />
351
</Svg>
352

353
// Image with different aspect ratio handling
354
<Svg width="300" height="200">
355
  <Image
356
    x="50"
357
    y="50"
358
    width="200"
359
    height="100"
360
    href="https://example.com/wide-image.jpg"
361
    preserveAspectRatio="xMinYMin slice"
362
  />
363
</Svg>
364
```
365

366
**Preserve Aspect Ratio Values:**
367

368
The `preserveAspectRatio` attribute controls how images are scaled and positioned:
369

370
- **Alignment**: `xMinYMin`, `xMidYMin`, `xMaxYMin`, `xMinYMid`, `xMidYMid`, `xMaxYMid`, `xMinYMax`, `xMidYMax`, `xMaxYMax`
371
- **Scaling**: `meet` (fit entirely), `slice` (fill area, may crop), `none` (stretch to fit)
372

373
```typescript
374
// Examples of different aspect ratio settings
375
<Image preserveAspectRatio="xMidYMid meet" />  // Center, fit entirely (default)
376
<Image preserveAspectRatio="xMinYMin slice" /> // Top-left, fill area
377
<Image preserveAspectRatio="none" />           // Stretch to fit exactly
378
```
379

380
## Container Organization Patterns
381

382
### Hierarchical Grouping
383

384
```typescript
385
<Svg width="300" height="200">
386
  <G id="scene">
387
    <G id="background" fill="lightgray">
388
      <Rect width="300" height="200" />
389
    </G>
390
    <G id="objects" transform="translate(50,50)">
391
      <G id="shape1" fill="red">
392
        <Circle cx="0" cy="0" r="30" />
393
      </G>
394
      <G id="shape2" fill="blue" transform="translate(100,0)">
395
        <Rect x="-20" y="-20" width="40" height="40" />
396
      </G>
397
    </G>
398
  </G>
399
</Svg>
400
```
401

402
### Reusable Component Library
403

404
```typescript
405
<Svg width="400" height="300">
406
  <Defs>
407
    {/* Define reusable components */}
408
    <Symbol id="house" viewBox="0 0 100 100">
409
      <Rect x="20" y="40" width="60" height="60" fill="brown" />
410
      <Polygon points="10,40 50,10 90,40" fill="red" />
411
      <Rect x="35" y="60" width="15" height="25" fill="darkbrown" />
412
      <Rect x="60" y="55" width="12" height="12" fill="lightblue" />
413
    </Symbol>
414
    
415
    <Symbol id="tree" viewBox="0 0 60 80">
416
      <Rect x="27" y="60" width="6" height="20" fill="brown" />
417
      <Circle cx="30" cy="40" r="20" fill="green" />
418
    </Symbol>
419
  </Defs>
420
  
421
  {/* Use components multiple times */}
422
  <Use href="#house" x="50" y="100" width="100" height="100" />
423
  <Use href="#house" x="200" y="120" width="80" height="80" />
424
  <Use href="#tree" x="20" y="150" width="60" height="80" />
425
  <Use href="#tree" x="320" y="140" width="60" height="80" />
426
  <Use href="#tree" x="150" y="80" width="40" height="60" />
427
</Svg>
428
```