> For the complete documentation index, see [llms.txt](https://help.brickspacelab.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.brickspacelab.com/keystone/guides/sitewide/set-up-mobile-specific-images.md).

# Set up mobile-specific images

Several Keystone sections support a separate **Mobile background image** so you can show a cropped or simplified asset on phones while keeping a wide desktop hero. Uploading a mobile image alone is not enough—you must enable the background image and understand the fallback rules.

Sections that support mobile background images include **Banner**, **Slideshow**, **Split banner**, and **Search banner**. Settings names match across these sections.

## Configure a mobile background image

{% stepper %}
{% step %}
**Open the section**

In **Customize**, select the section (for example **Banner** on your homepage).
{% endstep %}

{% step %}
**Upload desktop and mobile images**

* **Image background desktop** — wide hero for tablet and desktop (`md` breakpoint and up)
* **Mobile background image** — portrait-friendly asset (760 × 1010 px recommended)

Enable **Show image** so the background image layer renders.
{% endstep %}

{% step %}
**Save and preview mobile**

Use the theme editor device preview or a real phone. Mobile images use the `block md:hidden` layer; desktop images use `hidden md:block`.
{% endstep %}
{% endstepper %}

| Setting                      | Purpose                                                     |
| ---------------------------- | ----------------------------------------------------------- |
| Image background desktop     | Background on desktop/tablet                                |
| Mobile background image      | Background on mobile when uploaded                          |
| Show image                   | Must be on for either image to display                      |
| Show video background mobile | Separate toggle if a video background should play on mobile |

## Fallback behavior

If **Mobile background image** is **empty**, Keystone **reuses the desktop image** on mobile (scaled for the smaller viewport). You do not need a separate mobile file unless you want different art direction.

If **Show image** is off, neither desktop nor mobile background images render regardless of uploads.

Video backgrounds follow their own mobile toggle (**Show video background mobile**). A mobile image does not replace video unless video is disabled or hidden on mobile.

## Verify the setup

1. Confirm **Show image** is enabled in the section settings.
2. Confirm the mobile file appears in **Mobile background image** (not only in a content block **Image** field—block images are separate from the section background).
3. Preview at mobile width. Desktop-only sections hidden via **Device visibility** will not show on phones at all.
4. Clear browser cache or use a private window if a previous hero image appears stuck.

## Common mistakes

| Mistake                                                    | Result                                                          |
| ---------------------------------------------------------- | --------------------------------------------------------------- |
| Image uploaded to a block, not **Mobile background image** | Background unchanged; block image may show in content area only |
| **Show image** disabled                                    | No background on any device                                     |
| Section set to **Show on desktop only**                    | Section (and its mobile image) never appears on phones          |
| Only mobile image uploaded, desktop empty                  | Mobile shows; desktop may show placeholder SVG                  |

## Related reading

* [Banner section reference](/keystone/sections/content-and-media/banner.md)
* [Device specific visibility](/keystone/guides/sitewide/device-specific-visibility.md)
* [Test responsive layouts without publishing the theme](https://github.com/BrickspaceLab/theme-docs/blob/main/general/general/test-responsive-layouts-without-publishing.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.brickspacelab.com/keystone/guides/sitewide/set-up-mobile-specific-images.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.