Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Flutter and app store releases

backgroundImage: url(...) does nothing in a React Native view

Errorstyle={{ backgroundImage: 'url(...)' }} has no effect

Short answer

In React Native the backgroundImage style draws linear and radial gradients, not pictures, so url(...) is ignored. Show a picture behind content by putting an Image inside a View, absolutely positioned to fill it, and give the container a width and height. If the picture is local, its require() path must be a fixed string.

  • Applies to React Native 0.8x, Android 9 and later, iOS 17 and later
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check which of the three ways to get a background you used: a backgroundImage style, an ImageBackground, or an Image inside a View. Then give the outer view a coloured background for a moment. If the coloured box is missing or has no height, the cause is the size of the container, not the picture.

    grep -rn "backgroundImage\|ImageBackground" src/
    # temporary, on the container:  style={{ backgroundColor: 'red' }}
  2. 2Match what you see, then jump to its fix

    1. 1The code comes from a web project: style={{ backgroundImage: `url(${img})` }} or a string with url() in it.backgroundImage is not a picture property in React NativeFix
    2. 2The coloured box from the first step is missing, or it is a thin strip, and ImageBackground shows nothing.The container has no width and heightFix
    3. 3A picture appears when you write the file name out, and nothing appears when the name comes from a variable, a prop or a template string.require() is given a path that is built at runtimeFix

What does the error look like?

  • style={{ backgroundImage: 'url(...)' }} has no effect
  • ImageBackground renders an empty area
  • The picture appears when require() gets a fixed path and disappears when the path is built from a variable

Cause 1 of 3

backgroundImage is not a picture property in React Native

1Check

The React Native style reference describes backgroundImage as drawing a linear-gradient or a radial-gradient with web-like syntax. It lists no url() form, so a picture never goes through it.

grep -rn "backgroundImage" src/

2Fix

Remove backgroundImage for pictures. Put an Image inside a View, stretch it over the view with the absolute fill style, and draw the content after it so it sits on top.

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

<View style={{ width: 300, height: 200 }}>
  <Image source={require('./bg.png')} style={StyleSheet.absoluteFill} />
  <Text>Content on top of the picture</Text>
</View>

3Verify

Reload the app. The picture covers the view and the text is drawn above it.

npx react-native start

Confirmed by reactnative.dev

Did this fix it?

Cause 2 of 3

The container has no width and height

1Check

The ImageBackground reference states that you must specify some width and height style attributes. The same page marks ImageBackground as deprecated in favour of a View with an absolutely positioned Image, which is what the first cause builds.

grep -rn -A4 "<ImageBackground" src/

2Fix

Give the component a size in its style, or let a parent with flex give it one.

<ImageBackground
  source={require('./bg.png')}
  style={{ width: '100%', height: 220 }}
>
  <Text>Title</Text>
</ImageBackground>

3Verify

The picture now fills a box of the size you set.

npx react-native start

Confirmed by reactnative.dev

Did this fix it?

Cause 3 of 3

require() is given a path that is built at runtime

1Check

The Images guide says the file name inside require has to be known statically, because the bundler reads it before the app runs.

grep -rnE "require\([^'\"]" src/ | head -n 20

2Fix

Call require with a literal path for every picture, and choose between the results at runtime.

// BAD: the path is computed
// <Image source={require('./' + name + '.png')} />

// GOOD: every picture has its own literal require
const bg = active
  ? require('./bg-active.png')
  : require('./bg-idle.png');
<Image source={bg} style={StyleSheet.absoluteFill} />

3Verify

The picture shows for both values of the condition.

grep -rn "require('./' +" src/

Confirmed by reactnative.dev

Did this fix it?

How do I stop it coming back?

  • Use backgroundImage only for gradients, and an Image behind the content for pictures.
  • Always give the container a size, or a flex parent that provides one.
  • Keep one small Background component in the project so every screen builds the picture and the content the same way.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.