0
# Media Components
1

2
Image display and media components with support for multiple source formats, caching, accessibility, and advanced image processing capabilities.
3

4
## Image
5

6
A powerful image component that handles loading, caching, error states, and accessibility. Supports multiple image formats, resize modes, and advanced styling options.
7

8
```javascript { .api }
9
const Image: React.ComponentType<ImageProps>;
10
```
11

12
**Props:**
13
- `source` - Image source: number (require), string (URL), or SourceObject
14
- `defaultSource` - Default image shown while loading or on error
15
- `resizeMode` - How image should be resized: `'cover'` | `'contain'` | `'stretch'` | `'center'` | `'repeat'` | `'none'`
16
- `style` - Image styling including dimensions and effects
17
- `blurRadius` - Blur effect radius in pixels
18
- `tintColor` - Color to tint the image
19
- `draggable` - Whether image can be dragged (default: false)
20
- `accessibilityLabel` - Screen reader description
21
- `onLoad` - Callback when image loads successfully
22
- `onLoadStart` - Callback when loading begins
23
- `onLoadEnd` - Callback when loading ends (success or error)
24
- `onError` - Callback when image fails to load
25
- `onProgress` - Callback for download progress updates
26
- `onLayout` - Layout change callback
27

28
**Static Methods:**
29
- `Image.getSize(uri, successCallback, errorCallback)` - Get image dimensions
30
- `Image.prefetch(uri)` - Preload image into cache
31
- `Image.queryCache(uris)` - Check cache status for URIs
32

33
**Source Types:**
34
```javascript
35
// Asset from bundle
36
source={require('./image.png')}
37

38
// Remote URL
39
source="https://example.com/image.jpg"
40

41
// Source object with options
42
source={{
43
  uri: 'https://example.com/image.jpg',
44
  headers: { Authorization: 'Bearer token' },
45
  cache: 'force-cache',
46
  scale: 2.0,
47
  width: 300,
48
  height: 200
49
}}
50

51
// Multiple sources for responsive images
52
source={[
53
  { uri: 'https://example.com/small.jpg', scale: 1 },
54
  { uri: 'https://example.com/large.jpg', scale: 2 }
55
]}
56
```
57

58
**Resize Modes:**
59
- `cover` - Scale image to fill container while maintaining aspect ratio (default)
60
- `contain` - Scale image to fit inside container while maintaining aspect ratio
61
- `stretch` - Stretch image to fill container exactly
62
- `center` - Center image without scaling
63
- `repeat` - Tile image to fill container
64
- `none` - Don't scale or move image from top-left corner
65

66
**Usage:**
67
```javascript
68
import { Image } from "react-native-web";
69

70
// Basic image
71
<Image
72
  source={{ uri: 'https://example.com/image.jpg' }}
73
  style={{ width: 200, height: 200 }}
74
  resizeMode="cover"
75
/>
76

77
// Image with loading states
78
<Image
79
  source={{ uri: 'https://example.com/image.jpg' }}
80
  defaultSource={{ uri: 'https://example.com/placeholder.jpg' }}
81
  style={{ width: 300, height: 200 }}
82
  onLoadStart={() => setLoading(true)}
83
  onLoad={() => {
84
    setLoading(false);
85
    console.log('Image loaded');
86
  }}
87
  onError={(error) => {
88
    setLoading(false);
89
    console.error('Image failed to load:', error);
90
  }}
91
/>
92

93
// Image with effects
94
<Image
95
  source={{ uri: 'https://example.com/photo.jpg' }}
96
  style={{ 
97
    width: 250, 
98
    height: 250,
99
    borderRadius: 125
100
  }}
101
  blurRadius={2}
102
  tintColor="rgba(255, 0, 0, 0.3)"
103
/>
104

105
// Responsive image with multiple sources
106
<Image
107
  source={[
108
    { 
109
      uri: 'https://example.com/small.jpg',
110
      width: 400,
111
      height: 300
112
    },
113
    { 
114
      uri: 'https://example.com/large.jpg',
115
      width: 800,
116
      height: 600
117
    }
118
  ]}
119
  style={{ width: '100%', height: 200 }}
120
  resizeMode="cover"
121
/>
122

123
// Asset from bundle
124
<Image
125
  source={require('../assets/logo.png')}
126
  style={{ width: 100, height: 50 }}
127
/>
128

129
// Image with custom headers
130
<Image
131
  source={{
132
    uri: 'https://api.example.com/protected-image.jpg',
133
    headers: {
134
      'Authorization': 'Bearer ' + token,
135
      'User-Agent': 'MyApp/1.0'
136
    },
137
    cache: 'force-cache'
138
  }}
139
  style={{ width: 200, height: 150 }}
140
/>
141

142
// Accessible image
143
<Image
144
  source={{ uri: 'https://example.com/chart.png' }}
145
  accessibilityLabel="Sales chart showing 25% increase in Q3"
146
  style={{ width: 300, height: 200 }}
147
/>
148
```
149

150
**Static Method Usage:**
151
```javascript
152
// Get image dimensions
153
Image.getSize(
154
  'https://example.com/image.jpg',
155
  (width, height) => {
156
    console.log(`Image dimensions: ${width}x${height}`);
157
  },
158
  (error) => {
159
    console.error('Failed to get image size:', error);
160
  }
161
);
162

163
// Prefetch images for better UX
164
await Image.prefetch('https://example.com/next-image.jpg');
165

166
// Check cache status
167
const cacheStatus = await Image.queryCache([
168
  'https://example.com/image1.jpg',
169
  'https://example.com/image2.jpg'
170
]);
171
console.log(cacheStatus); // { 'image1.jpg': 'disk/memory', ... }
172
```
173

174
## ImageBackground
175

176
A container component that displays an image as a background while allowing child content to be rendered on top of it.
177

178
```javascript { .api }
179
const ImageBackground: React.ComponentType<ImageBackgroundProps>;
180
```
181

182
**Props:**
183
- Inherits all `ImageProps`
184
- `children` - Content to render over the background image
185
- `imageStyle` - Style applied specifically to the background image
186
- `imageRef` - Ref to access the underlying Image component
187
- `style` - Style applied to the container View
188

189
**Usage:**
190
```javascript
191
import { ImageBackground, Text, View } from "react-native-web";
192

193
// Basic background image
194
<ImageBackground
195
  source={{ uri: 'https://example.com/background.jpg' }}
196
  style={{ width: 300, height: 200, justifyContent: 'center' }}
197
>
198
  <Text style={{ color: 'white', fontSize: 18, textAlign: 'center' }}>
199
    Content over image
200
  </Text>
201
</ImageBackground>
202

203
// Background with custom image styling
204
<ImageBackground
205
  source={{ uri: 'https://example.com/pattern.jpg' }}
206
  style={{
207
    flex: 1,
208
    padding: 20
209
  }}
210
  imageStyle={{
211
    opacity: 0.3,
212
    resizeMode: 'repeat'
213
  }}
214
  resizeMode="repeat"
215
>
216
  <View style={{ backgroundColor: 'rgba(255,255,255,0.8)', padding: 15 }}>
217
    <Text>This content appears over a semi-transparent repeating background</Text>
218
  </View>
219
</ImageBackground>
220

221
// Hero section with background
222
<ImageBackground
223
  source={{ uri: 'https://example.com/hero.jpg' }}
224
  style={{
225
    width: '100%',
226
    height: 400,
227
    justifyContent: 'center',
228
    alignItems: 'center'
229
  }}
230
  imageStyle={{
231
    opacity: 0.7
232
  }}
233
>
234
  <View style={{
235
    backgroundColor: 'rgba(0,0,0,0.5)',
236
    padding: 20,
237
    borderRadius: 10
238
  }}>
239
    <Text style={{
240
      color: 'white',
241
      fontSize: 24,
242
      fontWeight: 'bold',
243
      textAlign: 'center'
244
    }}>
245
      Welcome to Our App
246
    </Text>
247
    <Text style={{
248
      color: 'white',
249
      fontSize: 16,
250
      textAlign: 'center',
251
      marginTop: 10
252
    }}>
253
      Discover amazing features
254
    </Text>
255
  </View>
256
</ImageBackground>
257

258
// Card with background image
259
<ImageBackground
260
  source={require('../assets/card-bg.jpg')}
261
  style={{
262
    width: 250,
263
    height: 150,
264
    borderRadius: 10,
265
    overflow: 'hidden'
266
  }}
267
  imageStyle={{
268
    borderRadius: 10
269
  }}
270
>
271
  <View style={{
272
    flex: 1,
273
    backgroundColor: 'rgba(0,0,0,0.3)',
274
    justifyContent: 'flex-end',
275
    padding: 15
276
  }}>
277
    <Text style={{ color: 'white', fontWeight: 'bold' }}>
278
      Card Title
279
    </Text>
280
    <Text style={{ color: 'white', fontSize: 12 }}>
281
      Card description text
282
    </Text>
283
  </View>
284
</ImageBackground>
285

286
// Accessing the image ref
287
function CustomImageBackground() {
288
  const imageRef = useRef();
289
  
290
  const handleImageLoad = () => {
291
    // Access image methods if needed
292
    console.log('Background image loaded');
293
  };
294
  
295
  return (
296
    <ImageBackground
297
      source={{ uri: 'https://example.com/bg.jpg' }}
298
      imageRef={imageRef}
299
      onLoad={handleImageLoad}
300
      style={{ flex: 1 }}
301
    >
302
      {/* Content */}
303
    </ImageBackground>
304
  );
305
}
306
```
307

308
## Types
309

310
```javascript { .api }
311
type ResizeMode = 'center' | 'contain' | 'cover' | 'none' | 'repeat' | 'stretch';
312

313
interface SourceObject {
314
  uri: string;
315
  headers?: Record<string, string>;
316
  body?: string;
317
  method?: string;
318
  cache?: 'default' | 'reload' | 'force-cache' | 'only-if-cached';
319
  scale?: number;
320
  width?: number;
321
  height?: number;
322
}
323

324
type Source = number | string | SourceObject | SourceObject[];
325

326
interface ImageStyle extends ViewStyle {
327
  resizeMode?: ResizeMode; // deprecated, use resizeMode prop
328
  tintColor?: ColorValue; // deprecated, use tintColor prop
329
}
330

331
interface ImageProps extends ViewProps {
332
  source?: Source;
333
  defaultSource?: Source;
334
  resizeMode?: ResizeMode;
335
  style?: ImageStyle;
336
  blurRadius?: number;
337
  tintColor?: ColorValue;
338
  draggable?: boolean;
339
  accessibilityLabel?: string;
340
  onLoad?: (event: LoadEvent) => void;
341
  onLoadStart?: () => void;
342
  onLoadEnd?: () => void;
343
  onError?: (event: ErrorEvent) => void;
344
  onProgress?: (event: ProgressEvent) => void;
345
  onLayout?: (event: LayoutEvent) => void;
346
}
347

348
interface ImageBackgroundProps extends ImageProps {
349
  children?: React.ReactNode;
350
  imageStyle?: ImageStyle;
351
  imageRef?: React.Ref<Image>;
352
  style?: ViewStyle; // Container style
353
}
354

355
// Static methods interface
356
interface ImageStatics {
357
  getSize: (
358
    uri: string,
359
    success: (width: number, height: number) => void,
360
    failure: (error: any) => void
361
  ) => void;
362
  prefetch: (uri: string) => Promise<void>;
363
  queryCache: (uris: string[]) => Promise<Record<string, 'disk/memory'>>;
364
}
365

366
// Events
367
interface LoadEvent {
368
  nativeEvent: {
369
    source: {
370
      width: number;
371
      height: number;
372
      uri: string;
373
    };
374
  };
375
}
376

377
interface ErrorEvent {
378
  nativeEvent: {
379
    error: string;
380
  };
381
}
382

383
interface ProgressEvent {
384
  nativeEvent: {
385
    loaded: number;
386
    total: number;
387
  };
388
}
389
```