backgroundImage: url(...) does nothing in a React Native view
style={{ backgroundImage: 'url(...)' }} has no effectShort 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.
Fix it fast
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' }}2Match what you see, then jump to its fix
- 1
The 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
The 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
A 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
- 1
What does the error look like?
style={{ backgroundImage: 'url(...)' }} has no effectImageBackground renders an empty areaThe 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 startConfirmed by reactnative.dev
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 startConfirmed by reactnative.dev
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 202Fix
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
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:
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- TaskvareA task and project-management suite: React on the web, Flutter on mobile, TypeScript underneath.
Related fixes
Mobile apps
A remote image in React Native shows nothing, or only for some URLs
The same component works with one URL and stays blank with another
A network image in React Native is blank for four reasons.
4 causes, each with a fixMobile apps
Axios request works on iOS or in a browser but fails on Android with Network Error
AxiosError: Network Error
A React Native app has no CORS, so on Android a Network Error usually means the request never reached the server.
3 causes, each with a fixMobile apps
Axios returns Network Error in a React Native app on iPhone or the iOS Simulator
error.code is ERR_NETWORK and error.response is undefined
A Network Error means iOS stopped the request before any HTTP answer came back.
3 causes, each with a fixMobile apps
A custom font in React Native falls back to the system font
Unrecognized font family 'MyFont'
React Native does not report a missing font, it just draws the system font.
6 causes, each with a fixMobile apps
fetch fails with TypeError: Network request failed in React Native
Network request failed
Network request failed means the request never got an HTTP response, so there is no status code to read.
3 causes, each with a fixMobile apps
react-native-geolocation-service getCurrentPosition fails or never returns
Location provider not available
Read the error code in the callback.
5 causes, each with a fix