react-native/website/versioned_docs/0.18/image.md

id, title, original_id

id	title	original_id
version-0.18-image	image	image

Image

A React component for displaying different types of images, including network images, static resources, temporary local images, and images from local disk, such as the camera roll.

Example usage:

renderImages: function() { return ( <View> <Image style={styles.icon} source={require('./myIcon.png')} /> <Image style={styles.logo} source={{uri: 'http://facebook.github.io/react/img/logo_og.png'}} /> </View> ); },

Edit on GitHubProps #

onLayout function #

Invoked on mount and layout changes with {nativeEvent: {layout: {x, y, width, height}}}.

onLoad function #

Invoked when load completes successfully

onLoadEnd function #

Invoked when load either succeeds or fails

onLoadStart function #

Invoked on load start

resizeMode enum('cover', 'contain', 'stretch') #

Determines how to resize the image when the frame doesn't match the raw image dimensions.

'cover': Scale the image uniformly (maintain the image's aspect ratio) so that both dimensions (width and height) of the image will be equal to or larger than the corresponding dimension of the view (minus padding).

'contain': Scale the image uniformly (maintain the image's aspect ratio) so that both dimensions (width and height) of the image will be equal to or less than the corresponding dimension of the view (minus padding).

'stretch': Scale width and height independently, This may change the aspect ratio of the src.

source {uri: string}, number #

uri is a string representing the resource identifier for the image, which could be an http address, a local file path, or the name of a static image resource (which should be wrapped in the require('./path/to/image.png') function).

style style #

Flexbox...

Transforms...

resizeMode Object.keys(ImageResizeMode)

backfaceVisibility enum('visible', 'hidden')

backgroundColor ColorPropType

borderColor ColorPropType

borderWidth number

borderRadius number

overflow enum('visible', 'hidden')

tintColor ColorPropType

opacity number

testID string #

A unique identifier for this element to be used in UI Automation testing scripts.

iosaccessibilityLabel string #

The text that's read by the screen reader when the user interacts with the image.

iosaccessible bool #

When true, indicates the image is an accessibility element.

ioscapInsets {top: number, left: number, bottom: number, right: number} #

When the image is resized, the corners of the size specified by capInsets will stay a fixed size, but the center content and borders of the image will be stretched. This is useful for creating resizable rounded buttons, shadows, and other resizable assets. More info on Apple documentation

iosdefaultSource {uri: string}, number #

A static image to display while loading the image source.

iosonError function #

Invoked on load error with {nativeEvent: {error}}

iosonProgress function #

Invoked on download progress with {nativeEvent: {loaded, total}}

Edit on GitHubExamples #

'use strict';

var React = require('react-native'); var { Image, StyleSheet, Text, View, ActivityIndicatorIOS } = React;

var base64Icon = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAEsAAABLCAQAAACSR7JhAAADtUlEQVR4Ac3YA2Bj6QLH0XPT1Fzbtm29tW3btm3bfLZtv7e2ObZnms7d8Uw098tuetPzrxv8wiISrtVudrG2JXQZ4VOv+qUfmqCGGl1mqLhoA52oZlb0mrjsnhKpgeUNEs91Z0pd1kvihA3ULGVHiQO2narKSHKkEMulm9VgUyE60s1aWoMQUbpZOWE+kaqs4eLEjdIlZTcFZB0ndc1+lhB1lZrIuk5P2aib1NBpZaL+JaOGIt0ls47SKzLC7CqrlGF6RZ09HGoNy1lYl2aRSWL5GuzqWU1KafRdoRp0iOQEiDzgZPnG6DbldcomadViflnl/cL93tOoVbsOLVM2jylvdWjXolWX1hmfZbGR/wjypDjFLSZIRov09BgYmtUqPQPlQrPapecLgTIy0jMgPKtTeob2zWtrGH3xvjUkPCtNg/tm1rjwrMa+mdUkPd3hWbH0jArPGiU9ufCsNNWFZ40wpwn+62/66R2RUtoso1OB34tnLOcy7YB1fUdc9e0q3yru8PGM773vXsuZ5YIZX+5xmHwHGVvlrGPN6ZSiP1smOsMMde40wKv2VmwPPVXNut4sVpUreZiLBHi0qln/VQeI/LTMYXpsJtFiclUN+5HVZazim+Ky+7sAvxWnvjXrJFneVtLWLyPJu9K3cXLWeOlbMTlrIelbMDlrLenrjEQOtIF+fuI9xRp9ZBFp6+b6WT8RrxEpdK64BuvHgDk+vUy+b5hYk6zfyfs051gRoNO1usU12WWRWL73/MMEy9pMi9qIrR4ZpV16Rrvduxazmy1FSvuFXRkqTnE7m2kdb5U8xGjLw/spRr1uTov4uOgQE+0N/DvFrG/Jt7i/FzwxbA9kDanhf2w+t4V97G8lrT7wc08aA2QNUkuTfW/KimT01wdlfK4yEw030VfT0RtZbzjeMprNq8m8tnSTASrTLti64oBNdpmMQm0eEwvfPwRbUBywG5TzjPCsdwk3IeAXjQblLCoXnDVeoAz6SfJNk5TTzytCNZk/POtTSV40NwOFWzw86wNJRpubpXsn60NJFlHeqlYRbslqZm2jnEZ3qcSKgm0kTli3zZVS7y/iivZTweYXJ26Y+RTbV1zh3hYkgyFGSTKPfRVbRqWWVReaxYeSLarYv1Qqsmh1s95S7G+eEWK0f3jYKTbV6bOwepjfhtafsvUsqrQvrGC8YhmnO9cSCk3yuY984F1vesdHYhWJ5FvASlacshUsajFt2mUM9pqzvKGcyNJW0arTKN1GGGzQlH0tXwLDgQTurS8eIQAAAABJRU5ErkJggg==';

var ImageCapInsetsExample = require('./ImageCapInsetsExample');

var NetworkImageCallbackExample = React.createClass({ getInitialState: function() { return { events: [], mountTime: new Date(), }; },

componentWillMount() { this.setState({mountTime: new Date()}); },

render: function() { var { mountTime } = this.state;

<span class="token keyword">return</span> <span class="token punctuation">(</span>
  &lt;View<span class="token operator">&gt;</span>
    &lt;Image
      source<span class="token operator">=</span><span class="token punctuation">{</span><span class="token keyword">this</span><span class="token punctuation">.</span>props<span class="token punctuation">.</span>source<span class="token punctuation">}</span>
      style<span class="token operator">=</span><span class="token punctuation">{</span><span class="token punctuation">[</span>styles<span class="token punctuation">.</span>base<span class="token punctuation">,</span> <span class="token punctuation">{</span>overflow<span class="token punctuation">:</span> <span class="token string">'visible'</span><span class="token punctuation">}</span><span class="token punctuation">]</span><span class="token punctuation">}</span>
      onLoadStart<span class="token operator">=</span><span class="token punctuation">{</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token operator">=</span><span class="token operator">&gt;</span> <span class="token keyword">this</span><span class="token punctuation">.</span><span class="token function">_loadEventFired<span class="token punctuation">(</span></span>`✔ onLoadStart <span class="token punctuation">(</span><span class="token operator">+</span>$<span class="token punctuation">{</span><span class="token keyword">new</span> <span class="token class-name">Date</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token operator">-</span> mountTime<span class="token punctuation">}</span>ms<span class="token punctuation">)</span>`<span class="token punctuation">)</span><span class="token punctuation">}</span>
      onLoad<span class="token operator">=</span><span class="token punctuation">{</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token operator">=</span><span class="token operator">&gt;</span> <span class="token keyword">this</span><span class="token punctuation">.</span><span class="token function">_loadEventFired<span class="token punctuation">(</span></span>`✔ onLoad <span class="token punctuation">(</span><span class="token operator">+</span>$<span class="token punctuation">{</span><span class="token keyword">new</span> <span class="token class-name">Date</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token operator">-</span> mountTime<span class="token punctuation">}</span>ms<span class="token punctuation">)</span>`<span class="token punctuation">)</span><span class="token punctuation">}</span>
      onLoadEnd<span class="token operator">=</span><span class="token punctuation">{</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token operator">=</span><span class="token operator">&gt;</span> <span class="token keyword">this</span><span class="token punctuation">.</span><span class="token function">_loadEventFired<span class="token punctuation">(</span></span>`✔ onLoadEnd <span class="token punctuation">(</span><span class="token operator">+</span>$<span class="token punctuation">{</span><span class="token keyword">new</span> <span class="token class-name">Date</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token operator">-</span> mountTime<span class="token punctuation">}</span>ms<span class="token punctuation">)</span>`<span class="token punctuation">)</span><span class="token punctuation">}</span>
    <span class="token operator">/</span><span class="token operator">&gt;</span>

    &lt;Text style<span class="token operator">=</span><span class="token punctuation">{</span><span class="token punctuation">{</span>marginTop<span class="token punctuation">:</span> <span class="token number">20</span><span class="token punctuation">}</span><span class="token punctuation">}</span><span class="token operator">&gt;</span>
      <span class="token punctuation">{</span><span class="token keyword">this</span><span class="token punctuation">.</span>state<span class="token punctuation">.</span>events<span class="token punctuation">.</span><span class="token function">join<span class="token punctuation">(</span></span><span class="token string">'\n'</span><span class="token punctuation">)</span><span class="token punctuation">}</span>
    &lt;<span class="token operator">/</span>Text<span class="token operator">&gt;</span>
  &lt;<span class="token operator">/</span>View<span class="token operator">&gt;</span>
<span class="token punctuation">)</span><span class="token punctuation">;</span>

},

_loadEventFired(event) { this.setState((state) => { return state.events = [...state.events, event]; }); } });

var NetworkImageExample = React.createClass({ getInitialState: function() { return { error: false, loading: false, progress: 0 }; }, render: function() { var loader = this.state.loading ? <View style={styles.progress}> <Text>{this.state.progress}%</Text> <ActivityIndicatorIOS style={{marginLeft:5}}/> </View> : null; return this.state.error ? <Text>{this.state.error}</Text> : <Image source={this.props.source} style={[styles.base, {overflow: 'visible'}]} onLoadStart={(e) => this.setState({loading: true})} onError={(e) => this.setState({error: e.nativeEvent.error, loading: false})} onProgress={(e) => this.setState({progress: Math.round(100 * e.nativeEvent.loaded / e.nativeEvent.total)})} onLoad={() => this.setState({loading: false, error: false})}> {loader} </Image>; } });

var ImageSizeExample = React.createClass({ getInitialState: function() { return { width: 0, height: 0, }; }, componentDidMount: function() { Image.getSize(this.props.source.uri, (width, height) => { this.setState({width, height}); }); }, render: function() { return ( <View style={{flexDirection: 'row'}}> <Image style={{ width: 60, height: 60, backgroundColor: 'transparent', marginRight: 10, }} source={this.props.source} /> <Text> Actual dimensions:{'\n'} Width: {this.state.width}, Height: {this.state.height} </Text> </View> ); }, });

exports.displayName = (undefined: ?string); exports.framework = 'React'; exports.title = '<Image>'; exports.description = 'Base component for displaying different types of images.';

exports.examples = [ { title: 'Plain Network Image', description: 'If the source prop uri property is prefixed with ' + '"http", then it will be downloaded from the network.', render: function() { return ( <Image source={{uri: 'http://facebook.github.io/react/img/logo_og.png'}} style={styles.base} /> ); }, }, { title: 'Plain Static Image', description: 'Static assets should be required by prefixing with image! ' + 'and are located in the app bundle.', render: function() { return ( <View style={styles.horizontal}> <Image source={require('image!uie_thumb_normal')} style={styles.icon} /> <Image source={require('image!uie_thumb_selected')} style={styles.icon} /> <Image source={require('image!uie_comment_normal')} style={styles.icon} /> <Image source={require('image!uie_comment_highlighted')} style={styles.icon} /> </View> ); }, }, { title: 'Image Loading Events', render: function() { return ( <NetworkImageCallbackExample source={{uri: 'http://facebook.github.io/origami/public/images/blog-hero.jpg?r=1'}}/> ); }, }, { title: 'Error Handler', render: function() { return ( <NetworkImageExample source={{uri: 'http://TYPO_ERROR_facebook.github.io/react/img/logo_og.png'}} /> ); }, platform: 'ios', }, { title: 'Image Download Progress', render: function() { return ( <NetworkImageExample source={{uri: 'http://facebook.github.io/origami/public/images/blog-hero.jpg?r=1'}}/> ); }, platform: 'ios', }, { title: 'Border Color', render: function() { return ( <View style={styles.horizontal}> <Image source={smallImage} style={[ styles.base, styles.background, {borderWidth: 3, borderColor: '#f099f0'} ]} /> </View> ); }, }, { title: 'Border Width', render: function() { return ( <View style={styles.horizontal}> <Image source={smallImage} style={[ styles.base, styles.background, {borderWidth: 5, borderColor: '#f099f0'} ]} /> </View> ); }, }, { title: 'Border Radius', render: function() { return ( <View style={styles.horizontal}> <Image style={[styles.base, {borderRadius: 5}]} source={fullImage} /> <Image style={[styles.base, styles.leftMargin, {borderRadius: 19}]} source={fullImage} /> </View> ); }, }, { title: 'Background Color', render: function() { return ( <View style={styles.horizontal}> <Image source={smallImage} style={styles.base} /> <Image style={[ styles.base, styles.leftMargin, {backgroundColor: 'rgba(0, 0, 100, 0.25)'} ]} source={smallImage} /> <Image style={[styles.base, styles.leftMargin, {backgroundColor: 'red'}]} source={smallImage} /> <Image style={[styles.base, styles.leftMargin, {backgroundColor: 'black'}]} source={smallImage} /> </View> ); }, }, { title: 'Opacity', render: function() { return ( <View style={styles.horizontal}> <Image style={[styles.base, {opacity: 1}]} source={fullImage} /> <Image style={[styles.base, styles.leftMargin, {opacity: 0.8}]} source={fullImage} /> <Image style={[styles.base, styles.leftMargin, {opacity: 0.6}]} source={fullImage} /> <Image style={[styles.base, styles.leftMargin, {opacity: 0.4}]} source={fullImage} /> <Image style={[styles.base, styles.leftMargin, {opacity: 0.2}]} source={fullImage} /> <Image style={[styles.base, styles.leftMargin, {opacity: 0}]} source={fullImage} /> </View> ); }, }, { title: 'Nesting', render: function() { return ( <Image style={{width: 60, height: 60, backgroundColor: 'transparent'}} source={fullImage}> <Text style={styles.nestedText}> React </Text> </Image> ); }, }, { title: 'Tint Color', description: 'The tintColor style prop changes all the non-alpha ' + 'pixels to the tint color.', render: function() { return ( <View> <View style={styles.horizontal}> <Image source={require('image!uie_thumb_normal')} style={[styles.icon, {borderRadius: 5, tintColor: '#5ac8fa' }]} /> <Image source={require('image!uie_thumb_normal')} style={[styles.icon, styles.leftMargin, {borderRadius: 5, tintColor: '#4cd964' }]} /> <Image source={require('image!uie_thumb_normal')} style={[styles.icon, styles.leftMargin, {borderRadius: 5, tintColor: '#ff2d55' }]} /> <Image source={require('image!uie_thumb_normal')} style={[styles.icon, styles.leftMargin, {borderRadius: 5, tintColor: '#8e8e93' }]} /> </View> <Text style={styles.sectionText}> It also works with downloaded images: </Text> <View style={styles.horizontal}> <Image source={smallImage} style={[styles.base, {borderRadius: 5, tintColor: '#5ac8fa' }]} /> <Image source={smallImage} style={[styles.base, styles.leftMargin, {borderRadius: 5, tintColor: '#4cd964' }]} /> <Image source={smallImage} style={[styles.base, styles.leftMargin, {borderRadius: 5, tintColor: '#ff2d55' }]} /> <Image source={smallImage} style={[styles.base, styles.leftMargin, {borderRadius: 5, tintColor: '#8e8e93' }]} /> </View> </View> ); }, }, { title: 'Resize Mode', description: 'The resizeMode style prop controls how the image is ' + 'rendered within the frame.', render: function() { return ( <View style={styles.horizontal}> <View> <Text style={[styles.resizeModeText]}> Contain </Text> <Image style={styles.resizeMode} resizeMode={Image.resizeMode.contain} source={fullImage} /> </View> <View style={styles.leftMargin}> <Text style={[styles.resizeModeText]}> Cover </Text> <Image style={styles.resizeMode} resizeMode={Image.resizeMode.cover} source={fullImage} /> </View> <View style={styles.leftMargin}> <Text style={[styles.resizeModeText]}> Stretch </Text> <Image style={styles.resizeMode} resizeMode={Image.resizeMode.stretch} source={fullImage} /> </View> </View> ); }, }, { title: 'Animated GIF', render: function() { return ( <Image style={styles.gif} source={{uri: 'http://38.media.tumblr.com/9e9bd08c6e2d10561dd1fb4197df4c4e/tumblr_mfqekpMktw1rn90umo1_500.gif'}} /> ); }, platform: 'ios', }, { title: 'Base64 image', render: function() { return ( <Image style={styles.base64} source={{uri: base64Icon, scale: 3}} /> ); }, platform: 'ios', }, { title: 'Cap Insets', description: 'When the image is resized, the corners of the size specified ' + 'by capInsets will stay a fixed size, but the center content and ' + 'borders of the image will be stretched. This is useful for creating ' + 'resizable rounded buttons, shadows, and other resizable assets.', render: function() { return <ImageCapInsetsExample />; }, platform: 'ios', }, { title: 'Image Size', render: function() { return <ImageSizeExample source={fullImage} />; }, platform: 'ios', }, ];

var fullImage = {uri: 'http://facebook.github.io/react/img/logo_og.png'}; var smallImage = {uri: 'http://facebook.github.io/react/img/logo_small_2x.png'};

var styles = StyleSheet.create({ base: { width: 38, height: 38, }, progress: { flex: 1, alignItems: 'center', flexDirection: 'row', width: 100 }, leftMargin: { marginLeft: 10, }, background: { backgroundColor: '#222222' }, sectionText: { marginVertical: 6, }, nestedText: { marginLeft: 12, marginTop: 20, backgroundColor: 'transparent', color: 'white' }, resizeMode: { width: 90, height: 60, borderWidth: 0.5, borderColor: 'black' }, resizeModeText: { fontSize: 11, marginBottom: 3, }, icon: { width: 15, height: 15, }, horizontal: { flexDirection: 'row', }, gif: { flex: 1, height: 200, }, base64: { flex: 1, height: 50, resizeMode: 'contain', }, });

Next →