Skip to main content
ImageBackground is a simple drop-in replacement for Image that allows you to nest child components on top of a background image.

​
Usage

import { ImageBackground, StyleSheet, Text } from 'react-native';

function App() {
  return (
    <ImageBackground
      source={{ uri: 'https://example.com/background.jpg' }}
      style={styles.background}
      imageStyle={styles.image}
    >
      <Text style={styles.text}>Content over background</Text>
    </ImageBackground>
  );
}

const styles = StyleSheet.create({
  background: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
  image: {
    opacity: 0.5,
  },
  text: {
    color: 'white',
    fontSize: 24,
  },
});

​
Props

ImageBackground accepts all Image props plus the following:
​
children
React.Node
Child components to render on top of the background image.
​
style
ViewStyleProp
Style applied to the outer View component. This controls the layout and dimensions of the entire ImageBackground.
​
imageStyle
ImageStyleProp
Style applied to the inner Image component. Use this to style the background image itself (e.g., opacity, resizeMode).
​
imageRef
React.RefSetter<Image>
Allows you to set a reference to the inner Image component.
​
source
ImageSource
The image source for the background. Can be a remote URL, local file resource, or static image.
// Remote URL
source={{ uri: 'https://example.com/image.jpg' }}

// Local file
source={require('./background.png')}
​
resizeMode
'cover' | 'contain' | 'stretch' | 'repeat' | 'center'
Determines how to resize the image when the frame doesn’t match the raw image dimensions.
  • cover: Scale uniformly (maintain aspect ratio) to fill the view
  • contain: Scale uniformly to fit within the view
  • stretch: Scale width and height independently
  • repeat: Repeat the image to cover the frame
  • center: Center the image without scaling up

​
Implementation Details

ImageBackground wraps your content in a View and renders an absolutely positioned Image as the background: 
<View style={style}>
  <Image {...props} style={[StyleSheet.absoluteFill, imageStyle]} />
  {children}
</View>
The outer View’s dimensions are determined by the style prop, while the background image fills the entire View using StyleSheet.absoluteFill.

​
Common Patterns

​
With Custom Opacity

<ImageBackground
  source={require('./background.jpg')}
  style={{ flex: 1 }}
  imageStyle={{ opacity: 0.3 }}
>
  <Text>Content with semi-transparent background</Text>
</ImageBackground>

​
With Blur Effect

<ImageBackground
  source={{ uri: 'https://example.com/image.jpg' }}
  blurRadius={10}
  style={{ flex: 1 }}
>
  <Text>Content over blurred background</Text>
</ImageBackground>

​
Responsive Background

<ImageBackground
  source={require('./bg.jpg')}
  style={{
    width: '100%',
    height: 200,
  }}
  resizeMode="cover"
>
  <View style={{ padding: 20 }}>
    <Text>Responsive content</Text>
  </View>
</ImageBackground>

Build docs developers (and LLMs) love

Get started for freeTalk to us