Background images can be applied to the Primary or Secondary section of a screen, adding a visual layer behind all other elements. Unlike the Image element, which is placed as a standalone content element on a screen, a background image is part of the screen or section itself — it sits behind everything else and fills the space you define.
If you need more flexibility, we recommend adding your image as an element.
Before you begin
Determine your screen layout to know how many images you need and how they will interact with your screen elements.
Prepare your background image file according to design specs.
Ensure text contrast and readability by planning for overlays or text box styling if needed.
Add an image to a single screen
From the Editor, select the screen you want to add the image background to.
In the Builder canvas, click on the Primary or Secondary section of the screen.
The left control panel will update to show that section's settings.
In the editor window, select the media upload icon.
Double click the image you want to use.
The image is added to the background.
Background image settings are applied per section, so the Primary and Secondary sections can each have their own independent background image.
Removing a Background Image
If a background image is already applied, a clear icon (X button) appears next to the image in the Media section of the control panel. Clicking it removes the background image and reverts the section to displaying only its background color.
Control Panel Options
Once a background image is applied, the following settings become available in the control panel.
Size Mode
Controls how the image fills the section. Three options are available:
Show All — displays the entire image without cropping. The full image is always visible, but if the image's proportions don't match the section's dimensions, the background color will show around the edges.
Fit the Space — scales the image to completely fill the section. No background color is visible, but parts of the image may be cropped to fill the space.
Original — displays the image at its actual pixel size with no scaling applied.
Positioning (9-Point Grid)
After uploading an image, a 9-point grid appears to control where the image is anchored within the section. This is especially useful when Fit the Space is selected — it determines which part of the image stays visible when cropping occurs.
The nine positions are:
Top Left · Top Center · Top Right Middle Left · Center · Middle Right Bottom Left · Bottom Center · Bottom Right
For example, if the main subject of your image is in the top-left corner, selecting Top Left ensures that area remains visible regardless of how the image is cropped to fit.
Image Transparency
Controls how transparent the background image appears, on a scale from 0% to 100%. Increasing the transparency allows the section's background color to show through the image. This is useful for creating a soft, layered look — for example, applying a light texture over a brand color.
Background Blur
A toggle that applies a blur effect to the background image. Useful when you want a background that adds visual depth without competing with foreground content.
Corner Radius
Rounds the corners of the section's background. Higher values produce more rounded corners. This applies to both the background color and the background image together.
Border Width
Sets the thickness of the border around the section in pixels. Set to 0 for no border.
Border Color
Sets the color of the border. A color picker allows you to input a hex value or select a color visually. Only has a visible effect when Border Width is greater than 0.
Shadow
A toggle that applies a default drop shadow to the section, adding depth and separation from other elements on the screen.
Alt Text
An accessible text description of the background image, read by screen readers in place of the image. Even for decorative backgrounds, adding alt text is recommended — if the image is purely decorative and conveys no meaning, you can note that explicitly.
Supported File Types & Specs
Background images follow the same file requirements as other image uploads:
Property | Recommendation |
Formats |
|
File size | ~300KB recommended, 1MB max |
Min resolution | 600 × 600px |
Tip: For full-bleed backgrounds, use a wider image (1920px or wider) to avoid visible stretching on large screens. Pair with Fit the Space and a center or middle position to keep the focal point visible across screen sizes.
Responsiveness & Image Cutoff
Background images respond to the window size of the device viewing the experience. Depending on the section and the image dimensions you use, parts of the image may be cut off — this is expected behavior when Fit the Space is selected, but it can also affect how much of the image is visible depending on the user's screen height or width.
Secondary Section on Desktop
The secondary section on desktop is typically wider than it is tall. If you use a wide landscape image, a significant portion of the top and bottom may be cut off. For desktop secondary backgrounds, taller images work better — they fill the vertical space of the section more naturally and lose less content when cropped.
Secondary Section on Mobile
On mobile, the secondary section tends to be taller relative to its width. If you use a tall portrait image, the left and right sides may be cut off. For mobile secondary backgrounds, wider images work better — they fill the horizontal space more effectively on narrower screens.
Swapping Images Per Device
Because the ideal image proportions differ between desktop and mobile, the best practice is to upload different images for each. Use Style Independently to apply a completely different background image for mobile vs. desktop:
Select the section.
Enable Style Independently for that section.
Switch to the Mobile view using the device switcher.
Upload a separate image optimized for mobile proportions.
This gives you full control over how the background appears on each device without compromise.
Background image settings can be applied independently for desktop and mobile using the Style Independently (SI) feature:
Toggle between Desktop and Mobile using the device switcher at the top of the editor.
Select the section.
Enable Style Independently for that section.
Upload a different background image, adjust the size mode, or change positioning for each device.
This is particularly useful when a background image that works well on desktop needs to be replaced or repositioned for mobile — for example, using a portrait-cropped version of the same image on mobile.
Quick Reference
Option | Where to Configure |
Add background image | Control panel → Media (file upload icon) |
Remove background image | Control panel → X button next to current image |
Size mode | Control panel → Show All / Fit the Space / Original |
Crop anchor | Control panel → 9-point positioning grid |
Image transparency | Control panel → Image Transparency (0–100%) |
Background blur | Control panel → Background Blur toggle |
Corner radius | Control panel → Corner Radius |
Border | Control panel → Border Width + Border Color |
Shadow | Control panel → Shadow toggle |
Alt text | Control panel → Alt Text |
Per-device backgrounds | Style Independently (SI) toggle |
Next steps
Preview your experience across device types to verify the background renders consistently.
Use color overlays or text styling to ensure accessibility.
FAQ
Can I use a GIF as a background?
No. Only static images (JPG, PNG) or videos are supported for backgrounds.
Why does my image look blurry?
Use high-resolution images sized for 1920x1080 or similar to prevent pixelation.
Is there a file size limit for background images?
While there isn’t a strict limit, we recommend optimizing for web (under 2MB) to reduce load times.
How can I adjust a background image so it doesn’t cut off content or overlap with text?
If you're trying to reposition a background image, such as moving it slightly higher to prevent overlapping text or ensure everything fits on one screen, note that background images can only be aligned to the top, middle, or bottom of the screen. This setting is found under Position when editing the background image. Because background images cannot be freely moved, a more flexible option is to add the image as an element instead of setting it as a background. This allows you to manually reposition it and reorder it in relation to other content on the screen.
Why is a background image appearing in the preview but not in the Editor view of my screen?
This often occurs when Dynamic Variants have been applied to the 'Primary Section' of the screen. These variants can conditionally display different background images that won’t appear in the default Editor view. To resolve this, check the Primary Section for any dynamic variants and remove them if they are no longer needed. If the image still shows in the preview but not in the editor, please contact support for assistance.