Layout & Structure
Background Image
Full-canvas background image with optional overlay and brightness control. Works in both the builder canvas and deployed apps - drop it in, pick an image, and the section is done.
Three overlay modes to control contrast and readability over the image.
Slide brightness below 1 to darken, above 1 to lighten - no image editing needed.
Available on all plans.
Four things worth knowing
Three overlay modes
none shows the raw image. solid puts a flat colour tint over it - good for brand colours at low opacity. gradient-bottom fades the bottom edge so text placed over it stays readable without a hard colour block.
Brightness without touching the image
The brightness prop layers a transparent black or white overlay to darken or lighten the image at render time. Set it once in the builder and it adjusts live - no need to re-export a darker version of the photo.
Always-fresh image loading
Cache is intentionally bypassed (cachePolicy=“none”) so replacing an image at the same S3 URL always shows the new version. The component also remounts when the URI changes, clearing any in-memory state.
Flexible sizing
Fills its container by default (100% × 100%). Pass customWidth or customHeight when a screen needs a fixed pixel size - handy for hero banners with a specific height target.
Find it, drop it, configure
Where to find itAdd it to any screen
- Component picker → Layout & Structure → Background Image.
- Drop it on any screen - hero, banner, or full-page background.
- Pick an image via the source prop - opens the device picker and uploads to S3 automatically.
Before you publishThree things to check
- Set overlayType and adjust overlayOpacity so foreground text is readable.
- Check brightness - the default is
1(unchanged). Darken or lighten as needed. - Confirm resizeMode is
coverunless the image has transparent edges that need containing.
Image, overlay, and sizing
| Prop | Type | Default | Description |
|---|---|---|---|
source | string | ” | Image URI - remote URL (S3, CDN) or local asset path. Use the image picker in the property panel. |
overlayType | select | ’gradient-bottom’ | none - raw image. solid - flat colour tint. gradient-bottom - bottom-fade effect. |
resizeMode | select | ’cover’ | cover fills and crops. contain letterboxes. stretch distorts to fill. center natural size. |
borderRadius | number | 0 | Corner radius applied to the image and all overlay layers. |
isPreview | boolean | false | Reserved - passed from the builder canvas. No rendering difference currently. |
customWidth | number | - | Override container width in pixels. Omit to use 100%. |
customHeight | number | - | Override container height in pixels. Omit to use 100%. |
Make it yours
Every overlay and brightness control below is yours to change. The defaults are a neutral starting point - adjust them to match the design without touching anything else.
| Prop | Default | What it controls |
|---|---|---|
overlayColor | #000000 | Hex colour for the overlay layer. |
overlayOpacity | 0.55 | Opacity of the overlay (0–1). |
blurRadius | 0 | Gaussian blur on the image. 0 = sharp. Higher = more blur. |
brightness | 1 | Brightness multiplier. Below 1 darkens, above 1 lightens, 1 = unchanged. |
Common mistakes to avoid
gradient-bottom is not a real gradient
It’s a translucent solid View at reduced opacity (overlayOpacity × 0.65), not a LinearGradient. This is intentional - the standalone app runner may not have the ExpoLinearGradient native module, which would crash the app. The visual result is close enough for most use cases.
Replacing the S3 image at the same key
Cache is set to none for exactly this reason - new content at the same URL always loads fresh. If you switch to unique filenames per upload, relax cachePolicy to “memory-disk” for better network performance.
Text not readable over the image
Increase overlayOpacity (try 0.7) or lower brightness to darken the image. For gradient-bottom, a higher opacity strengthens the fade - the overlay opacity is multiplied by 0.65 internally, so push it higher than you’d expect.
Fixed height hero banners
The component fills its container by default. For a specific pixel height - say a 300 px hero strip - pass customHeight=300. The placement hook (useComponentPlacement) controls the default canvas dimensions registered for this component.