Background images in React Native

React Native has no CSS background-image, and its old shortcut is now deprecated. Here is the pattern to use instead, and how to size, overlay and theme the image.

8 min read
Smartphone with a teal gradient background on its screen under floating glass layers
In short
  • The React Native docs now mark ImageBackground as deprecated. Use a View with an absolutely positioned Image instead.
  • Use resizeMode="cover" for full-screen backgrounds and "repeat" only for small seamless tiles.
  • A full-screen image on a 3x phone decodes to about 12 MB of memory. Size files to the screen, not larger.
  • Put a dark overlay between the image and the text, and swap the file for dark mode with useColorScheme.
12 MBDecoded size of one full-screen image on a 3x phone
5resizeMode values in React Native
4.5:1Minimum contrast for body text (WCAG AA)

React Native has no CSS background-image. For years the answer was the <ImageBackground> component. The official ImageBackground page now marks it as deprecated and points to a plain View with an absolutely positioned Image. This guide shows that pattern, then covers the parts that decide whether a background looks sharp and loads fast: resize modes, file sizes, overlays, dark mode and splash screens.

The same rules apply whether you build the screens yourself or hand them to a React Native app development company. A background is an image like any other. It has a pixel size, a memory cost and a contrast problem, and all three are easy to check before release.

If you come from the web, the ideas will feel familiar. Our guides to responsive background images and fast background images cover the CSS side. Here the tools are different, but the budget thinking is the same.

What changed with ImageBackground?

The component still works, but it is no longer the recommended path. The current docs label it deprecated with one line of advice: use a View with an absolutely positioned Image.

That is not a big change in practice. ImageBackground was always a thin wrapper. It rendered a container View, placed an Image inside it with absolute positioning, and drew your children on top. The docs themselves said the implementation was basic and suggested writing your own component when needed.

Two props caused most of the confusion:

  • style styled the outer container.
  • imageStyle styled the inner image. Rounded corners, for example, had to go here.

When you write the pattern yourself, that split disappears. You style the container and the image directly, and you can see exactly what each layer does. Existing screens do not need an emergency rewrite. Migrate them when you touch them, and use the plain pattern for new code.

How do you build a background without ImageBackground?

Stack three layers in one container: the image, an optional overlay, and the content. The image and the overlay fill the container with StyleSheet.absoluteFill. The content sits on top in normal layout flow.

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

export function BackgroundScreen({ children }) {
  return (
    <View style={styles.root}>
      <Image
        source={require('./assets/bg-paper.jpg')}
        style={StyleSheet.absoluteFill}
        resizeMode="cover"
        accessible={false}
      />
      <View style={styles.overlay} />
      <View style={styles.content}>{children}</View>
    </View>
  );
}

const styles = StyleSheet.create({
  root: { flex: 1 },
  overlay: { ...StyleSheet.absoluteFillObject, backgroundColor: 'rgba(8, 9, 10, 0.45)' },
  content: { flex: 1, padding: 24 },
});

Three details matter here:

  1. The container needs a size. flex: 1 on a screen root is enough. Inside a card, give it an explicit height or let its content define one.
  2. Order is paint order. Later siblings draw on top, so the image comes first and the content last.
  3. Decorative images stay out of the accessibility tree. A texture tells a screen reader nothing, so mark it as not accessible.

Rounded corners work on the container: add borderRadius and overflow: 'hidden' to root, and the image is clipped with it.

Which resizeMode should a background use?

Use cover for almost every full-screen background. It scales the image evenly until it fills the frame, then crops what is left over. It is also the default.

The Image reference lists five values:

resizeModeWhat it doesUse it for
coverKeeps the aspect ratio, fills the frame, crops the overflowFull-screen and hero backgrounds
containKeeps the aspect ratio, fits the whole image inside the frameArtwork that must not be cropped. Leaves empty bands
stretchScales width and height separatelyFlat colors and soft gradients only. Distorts anything with detail
repeatTiles the image across the frameSmall seamless textures
centerCenters the image, scales down only if it is larger than the frameSmall decorative marks on a solid color

Plan for cover cropping

Phones are tall. A 4:3 image like our 1600×1200 files will lose its left and right edges on a portrait screen. Keep the important part of the texture near the center, or use a pattern with no single focal point. Abstract sets such as soft gradient mesh backgrounds survive any crop.

Use repeat only for true tiles

repeat shows every seam. The tile has to be made for it, as explained in our guide to seamless tileable textures. Keep tiles small, for example 256 or 512 pixels square, because a large tile gives no saving over one full image.

How big should a background file be on a phone?

Size it to the largest screen you support, in physical pixels, and stop there. The file size on disk is not the real cost. Once decoded, every pixel takes 4 bytes of memory, whatever the format.

ImagePixelsDecoded in memory
iPhone 15 Pro screen (393×852 points at 3x)1179×2556about 12 MB
Web Backgrounds file1600×1200about 7.7 MB
Same file resized to 1200×9001200×900about 4.3 MB
512×512 seamless tile512×512about 1 MB

A background that is twice the screen size costs four times the memory and buys nothing. On a long list of cards, each with its own background, that adds up fast.

Ship density variants for local files

For bundled images, React Native picks the right file by suffix. Save bg-paper.jpg, bg-paper@2x.jpg and bg-paper@3x.jpg next to each other and require('./bg-paper.jpg') loads the one that matches the screen density.

Let Android downsample large files

On Android, the resizeMethod prop controls how a large image is scaled. resize shrinks the image in memory before decoding, which helps when the file is much larger than the view. auto, the default, picks between resize and scale for you. Avoid none: it decodes at full resolution and can crash on big files.

How do you keep text readable on top?

Put a semi-transparent layer between the image and the text. A black overlay at 40 to 55 percent opacity is a common starting point for white text on a busy texture.

The target is the WCAG contrast minimum of 4.5:1 for body text and 3:1 for large text. Check it on the brightest area of the image that can end up behind text, not on the average. Our article on readable text on background images walks through the measurement.

Two more options help when an overlay alone looks heavy:

  • Blur the image. The blurRadius prop softens detail so text stands out. On iOS, values above 5 are needed for a visible effect.
  • Use a calmer file. Low-contrast paper, linen or grain textures need far less overlay than photos with sharp edges.

How do you switch backgrounds for dark mode?

Read the system theme with the useColorScheme hook and pick the source from it. The hook returns 'light' or 'dark' and updates when the user changes the setting.

import { useColorScheme } from 'react-native';

const BG = {
  light: require('./assets/bg-paper-light.jpg'),
  dark: require('./assets/bg-paper-dark.jpg'),
};

const scheme = useColorScheme();
const source = scheme === 'dark' ? BG.dark : BG.light;

Keep the require calls static, as above. The bundler resolves them at build time, so a path built from a variable will not work.

A dark variant is not the light file with the brightness turned down. Lower the contrast inside the texture, avoid pure white highlights, and keep the overall tone close to your dark surface color. Our notes on using backgrounds in dark mode cover the visual side in more detail.

Should backgrounds be bundled or loaded from a URL?

Bundle backgrounds that appear on first launch or on core screens. They are available offline, render on the first frame and need no width or height in the code.

Load from a URL when backgrounds change often, such as seasonal themes or content managed from a CMS. Remote images need a few extra steps:

  1. Give the image an explicit size, or let absoluteFill size it from the container.
  2. Call Image.prefetch(url) before the screen opens, so the image is already in the cache.
  3. Show a solid color in the container's backgroundColor while the image loads. It prevents a white flash. The defaultSource prop also works, but Android ignores it in debug builds.
  4. Serve a resized file for the device. Sending a 4000-pixel original to a phone wastes both data and memory.

If you use Expo, the expo-image package adds disk caching, a contentFit prop that mirrors resizeMode, and blurred placeholders. It is a good fit for screens with many remote backgrounds.

What about splash and onboarding screens?

Keep the splash screen simple and show the rich background on the first React Native screen. The splash screen is drawn by the operating system before your JavaScript runs, so React Native components cannot style it.

The platforms also limit what it can show. On Android 12 and later, the system splash screen API displays an app icon on a solid background color. A full-bleed image is not part of that design. iOS launch screens are more flexible, but a launch screen that looks very different on each platform feels inconsistent.

A pattern that works on both:

  1. Splash: icon on a solid color taken from the darkest tone of your background.
  2. First screen: the same solid color in the container, with the background image fading in once it has loaded.
  3. Onboarding: one background per step at most, from the same family of textures, so the screens feel connected.

The matching color makes the hand-off from splash to app feel seamless, even though two different systems draw it.

A checklist before you ship

  • New screens use a View plus an absolutely positioned Image, not ImageBackground.
  • Full-screen backgrounds use cover, and the key area survives a portrait crop.
  • No file is larger than the biggest supported screen in physical pixels.
  • Bundled images have @2x and @3x variants.
  • Text on top reaches 4.5:1 contrast on the brightest part of the image.
  • Dark mode loads its own variant, not a dimmed copy.
  • Remote backgrounds are prefetched and show a solid color while loading.
  • The splash color matches the first screen's background color.

Need a starting point? Browse background textures for calm surfaces that work behind text, or the subtle grain gradient set for soft full-screen backgrounds that crop well on tall screens.

Questions about React Native backgrounds

Is ImageBackground removed from React Native?

No. The docs mark it as deprecated, which means it still works but is no longer recommended. New code should use a View with an absolutely positioned Image, and existing screens can be migrated when you next change them.

Why does my background image not show up?

Usually the container has no size. An absolutely positioned image fills its parent, so the parent needs flex: 1 or an explicit height. Remote images also need a size, from the container or from width and height styles.

What resolution should a mobile background image be?

Match the largest screen you support in physical pixels. For a modern 3x phone that is about 1179 by 2556 pixels. Larger files cost more memory without looking sharper.

Can I use a CSS gradient as a background in React Native?

React Native core has no CSS background-image. Most projects use a gradient package such as expo-linear-gradient, or a gradient image file placed with the same absolutely positioned Image pattern.

How do I tile a small texture across a screen?

Use resizeMode set to repeat with a small seamless tile, for example 256 or 512 pixels square. The tile must be designed to repeat, or the seams will show.

Keep reading

Built for the web.
Free to download.