> For the complete documentation index, see [llms.txt](https://uxsmart.gitbook.io/velare/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://uxsmart.gitbook.io/velare/customize-your-pages/banners/image-with-text-overlay.md).
# Image with text overlay
**Image with text overlay** places a heading, a sentence, and a button directly on top of a wide picture, so the message and the imagery are read as one banner. It is the section most stores use for the hero at the top of the homepage, or for a campaign strip that should feel bold rather than quiet. Separate desktop and mobile images mean the crop stays right on both, and an adjustable overlay keeps the wording legible over a busy photo.
Reach for this section when the picture is doing the selling. When the message needs more words than fit comfortably over a photo, use [Image with text](/velare/customize-your-pages/banners/image-with-text.md) instead.
### Where to find it
{% hint style="success" %}
**Steps:**
1. Go to **Online Store > Themes > Customize**.
2. Open the template where the banner should appear, usually the homepage.
3. Click **Add section** and choose **Image with text overlay** from the **Banners** group.
4. Upload the desktop image, then upload a separate mobile image.
5. Add the heading and button blocks, then raise **Image overlay opacity** until the wording is comfortable to read.
{% endhint %}
*Result:* the banner fills the width you chose, with the wording positioned over the picture according to the content settings below.
### Section settings
#### General settings
| Setting | Description |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Section width** |
How far the banner spreads across the screen.
Stretch width: the picture runs close to both screen edges whatever the screen size.
Fixed width: the banner lines up with the page width set in Theme settings > Layout, so it sits on the same grid as the rest of the page.
Full width: the banner fills the whole browser window and resizes with it, the usual choice for a hero.
|
| **Color scheme** | The colours used for the wording and any button on the banner. Schemes are defined in **Theme settings > Colors**, so pick one whose text colour reads clearly against your photo. |
#### Image
| Setting | Description |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Image** | The picture shoppers see on desktop, sharpest at ***(1392px x 500px recommended)***. Leave calm space in the area where the wording will sit. |
| **Mobile image** | A separate picture for phones, sharpest at ***(400px x 469px recommended)***. Without it the desktop photo is cropped to a tall frame and the subject often falls outside it. |
| **Image overlay opacity** | Darkens the picture behind the wording. Raise it until the heading is easy to read, lower it when the photo is already calm and the text is drowning it out. |
| **Image height** | How tall the banner is. A taller banner commands more of the first screen, a shorter one lets shoppers reach the content below it sooner. |
#### Content settings
| Setting | Description |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Desktop content position** | Where the wording sits over the picture on wide screens. Move it to whichever corner or edge of your photo is emptiest, so the text never covers the subject. |
| **Content alignment** |
Where each line starts inside the text block.
Left: easiest to read for more than a few words.
Center: suits a short headline with one button, the common hero look.
Right: use when the subject of the photo sits on the left.
|
| **Max width** | How wide the block of wording is allowed to grow. Keeping it narrower than the banner stops long headlines from stretching edge to edge and becoming hard to scan. |
| **Padding inline** | Space to the left and right inside the text block. Increase it when the wording touches the edge of the banner on smaller screens. |
| **Padding block** | Space above and below inside the text block. Increase it when heading, description, and button feel packed together. |
#### Mobile layout
| Setting | Description |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Show text below on mobile** | Moves the wording out from over the picture and places it underneath on phones. Turn it on when the overlay makes the heading hard to read on a small screen. |
| **Content alignment** |
Where each line starts on phones, set separately from desktop.
Left: the safest for a heading that wraps onto several lines.
Center: keeps a short headline and button balanced.
Right: rarely needed, use it only to match a mobile image whose subject sits left.
|
#### Section divider
| Setting | Description |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **Show divider** | Draws a thin horizontal line at the section edge, useful when this banner and its neighbour share a background colour and run into each other. |
#### Section padding
| Setting | Description |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Top** | Space added above the banner. Set it to zero when the banner is the first thing on the page and should sit tight under the header. |
| **Bottom** | Space added below the banner. Increase it when the next section feels cramped against it. |
### Block settings
#### Heading, Subheading, Description
| Setting | Description |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Heading, Subheading, Description** | The three pieces of wording on the banner: the line shoppers read first, a short label above it for context, and a sentence below spelling out the offer. |
| **Width** |
How much horizontal room the wording takes inside the text block.
Fit: the text stays only as wide as the words themselves.
Fill: the text spans the full width of the block, which suits longer sentences.
|
| **Typography - Preset** | The font, size, and weight of the wording, taken from the presets in **Theme settings > Typography**. Choose a large preset for a hero, a smaller one for a mid page strip. |
| **Background** | Puts a solid panel behind the wording. Turn it on when the photo is too detailed for overlay opacity alone to make the text readable. |
| **Background color** |
The colour of that panel. Pick one with enough contrast against the wording, or you gain a panel and lose the readability you added it for.
Note: only appears when Background is enabled.
|
| **Corner radius** |
How rounded the corners of that panel look. Higher values soften the shape, 0 keeps the corners square.
Note: only appears when Background is enabled.
|
| **Padding top/bottom** | Breathing room above and below the wording. Increase it when the text presses against the edge of its panel. |
#### Button
| Setting | Description |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Button label** | The words shoppers click. Leave it empty and no button is shown at all, which turns the hero into a picture with no next step. |
| **Button link** | Where that click takes shoppers, usually the collection or campaign page the banner promotes. |
| **Button type** |
How much the button stands out over the picture.
Primary: solid and filled, the clearest choice over photography.
Outline: bordered and lighter, for a secondary action.
Link: plain underlined text, which can disappear against a busy image.
|
| **Spacing bottom** | Space left under the button. Increase it when the button sits too close to the bottom edge of the banner. |
### What changes on the storefront
* Shoppers see one wide banner with the wording laid over the photo, or beneath it on phones if **Show text below on mobile** is on.
* Raising **Image overlay opacity** darkens the picture across the whole banner, not only behind the text, so it changes the mood of the image as well as its readability.
* Without a **Mobile image** the desktop photo is reused and cropped on phones, which often cuts off the subject.
### Related pages
* [Banners](/velare/customize-your-pages/banners.md): the group this section belongs to
* [Image with text](/velare/customize-your-pages/banners/image-with-text.md): the version that keeps the wording beside the picture instead of over it
* [Video with text overlay](/velare/customize-your-pages/banners/video-with-text-overlay.md): the same layout with a video behind the wording
* [Colors](/velare/set-up-your-store/colors.md) and [Typography](/velare/set-up-your-store/typography.md): where the schemes and font presets come from
---
# 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, and the optional `goal` query parameter:
```
GET https://uxsmart.gitbook.io/velare/customize-your-pages/banners/image-with-text-overlay.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.