> 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/storytelling/multi-content/theme-block-media-with-text.md).

# Group block - Media with text

**Media with text** is the block that carries a complete message on its own inside a [Multi-content](/velare/customize-your-pages/storytelling/multi-content.md) row: a picture or video, wording over it or under it, an optional badge, and a button. It is the block to use when a column has to sell something rather than just illustrate it, for example a seasonal campaign, a category shortcut, or a product feature that needs a headline and a place to click.

Shoppers see it as a card in the row, and the wording can sit over the media for a banner look or below it for a cleaner editorial look.

<figure><img src="/files/erFNa3QokRtTE11zrQv6" alt=""><figcaption></figcaption></figure>

### Where to find it <a href="#where-to-find-it" id="where-to-find-it"></a>

{% hint style="success" %}
**Steps:**

1. Go to **Online Store > Themes > Customize**.
2. In the left sidebar, click the **Multi-content** section.
3. Click **Add block** and choose **Media with text**.
4. Upload the image or video, then fill in the wording and the button.
   {% endhint %}

*Result:* the block renders as one column of the row, with the wording placed over or under the media according to **Content position**.

### Settings <a href="#general-setting" id="general-setting"></a>

#### General <a href="#general" id="general"></a>

<figure><img src="/files/f4UhiV6PNyIXZyzRkOk2" alt=""><figcaption></figcaption></figure>

<table data-search="false"><thead><tr><th>Setting</th><th>Description</th></tr></thead><tbody><tr><td><strong>Color scheme</strong></td><td>The background and text colors this card uses. Schemes are defined in <strong>Theme settings > Colors</strong>. Give a card its own scheme when it should stand out from the rest of the row.</td></tr><tr><td><strong>Image ratio</strong></td><td><p>The shape the media is cropped to, which keeps cards of different source images looking consistent.</p><ul><li><strong>Adapt to image</strong>: no cropping, the media keeps its own shape.</li><li><strong>Square (1:1)</strong>: neutral, easy to pair with other cards.</li><li><strong>Portrait (3:4)</strong>: taller, gives overlaid wording more room.</li><li><strong>Landscape (4:3)</strong>: wider, suits scenes and interiors.</li><li><strong>Product (4:5)</strong>: matches the crop used on product cards.</li><li><strong>Golden (1.618:1)</strong>: the widest option, closest to a banner.</li></ul></td></tr><tr><td><strong>Vertical alignment</strong></td><td><p>Where this card sits against taller cards beside it.</p><ul><li><strong>Top</strong>: lines its top edge up with its neighbours.</li><li><strong>Middle</strong>: centres it, the safest choice when card heights differ.</li><li><strong>Bottom</strong>: drops it so the bottom edges match.</li></ul></td></tr><tr><td><strong>Width</strong></td><td>How much of the row this card claims. Give the leading promotion the larger share and let the supporting cards take less.</td></tr></tbody></table>

#### Media <a href="#media" id="media"></a>

<figure><img src="/files/9o1KMKdHLEvtffLINgT6" alt=""><figcaption></figcaption></figure>

<table data-search="false"><thead><tr><th>Setting</th><th>Description</th></tr></thead><tbody><tr><td><strong>Image</strong></td><td>The picture desktop shoppers see on this card, sharpest at <em><strong>(950px x 844px recommended)</strong></em></td></tr><tr><td><strong>Mobile image</strong></td><td>A second version for phones, sharpest at <em><strong>(475px x 422px recommended)</strong></em>. Crop it tighter, because the desktop shot loses its subject on a narrow screen.</td></tr><tr><td><strong>Video</strong></td><td>A clip that plays in place of the picture, which draws far more attention but costs more to load. Use it on one card, not on every card in the row.<br><em>* Note: Overrides the image setting. <strong>(950px x 844px recommended)</strong></em></td></tr><tr><td><strong>Link</strong></td><td>Where a click on the picture leads, so the whole card becomes clickable and not just the button. Videos are not affected by this setting.</td></tr></tbody></table>

#### Content settings <a href="#content-settings" id="content-settings"></a>

<figure><img src="/files/T5zG5nnKw2CBIqNErDPR" alt=""><figcaption></figcaption></figure>

<table data-search="false"><thead><tr><th>Setting</th><th>Description</th></tr></thead><tbody><tr><td><strong>Content position</strong></td><td><p>Whether the wording sits on the media or under it.</p><ul><li><strong>Overlay image</strong>: the wording sits on the picture, which reads as a banner but needs a photo with a calm area.</li><li><strong>Below image</strong>: the wording sits underneath, which is always readable and suits longer text.</li></ul></td></tr><tr><td><strong>Content alignment</strong></td><td><p>Which edge the wording lines up with.</p><ul><li><strong>Left</strong>: easiest to read for a full sentence.</li><li><strong>Center</strong>: suits a short headline and a single button.</li><li><strong>Right</strong>: use it when the subject of the photo sits on the left.</li></ul></td></tr></tbody></table>

#### Overlay image settings <a href="#overlay-image-settings" id="overlay-image-settings"></a>

<table data-search="false"><thead><tr><th>Setting</th><th>Description</th></tr></thead><tbody><tr><td><strong>Overlay opacity</strong></td><td>How strongly the picture is darkened behind the wording. Raise it until the text is comfortable to read, then stop, since every step also hides more of the photo.<br><em>* Note: Only appears when <strong>Content position</strong> is set to <strong>Overlay image</strong></em></td></tr><tr><td><strong>Desktop content position</strong></td><td>Which corner or edge of the picture the wording sits in on desktop, for example <strong>Top left</strong>, <strong>Center</strong>, <strong>Bottom left</strong> or <strong>Bottom right</strong>. Choose the area of the photo with the least detail.</td></tr></tbody></table>

#### Badge settings <a href="#badge-settings" id="badge-settings"></a>

<table data-search="false"><thead><tr><th>Setting</th><th>Description</th></tr></thead><tbody><tr><td><strong>Show badge</strong></td><td>Adds a small tag on the media, the quickest way to mark a card as new, limited, or on sale.</td></tr><tr><td><strong>Badge</strong></td><td>The words inside that tag. Two or three words at most, since it is meant to be read at a glance.<br><em>* Note: Only appears when <strong>Show badge</strong> is enabled</em></td></tr><tr><td><strong>Select icon</strong></td><td>A small symbol shown next to the badge wording, useful for reinforcing the meaning without adding more text.</td></tr><tr><td><strong>Background color</strong></td><td>The color of the tag itself. A contrasting color makes it read as urgent, a brand color keeps it quieter.</td></tr><tr><td><strong>Text color</strong></td><td>The color of the wording inside the tag. Check it against the background color, because a low contrast badge is worse than no badge.</td></tr><tr><td><strong>Vertical position</strong></td><td>Whether the tag sits at the <strong>Top</strong> or the <strong>Bottom</strong> of the media. Top is noticed first, bottom keeps the subject of the photo clear.</td></tr></tbody></table>

### Block settings <a href="#block-settings" id="block-settings"></a>

#### Heading, Subheading, Description <a href="#heading-subheading-description" id="heading-subheading-description"></a>

<table data-search="false"><thead><tr><th>Setting</th><th>Description</th></tr></thead><tbody><tr><td><strong>Heading, Subheading, Description</strong></td><td>The three lines of wording on the card: the big line shoppers read first, a short label above it for context, and a sentence below spelling out the offer.</td></tr><tr><td><strong>Width</strong></td><td><p>How much horizontal room the wording is allowed inside the card.</p><ul><li><strong>Fit</strong>: the text stays only as wide as the words themselves.</li><li><strong>Fill</strong>: the text spans the full width of the card.</li></ul></td></tr><tr><td><strong>Typography - Preset</strong></td><td>The font, size, and weight of the wording, taken from the presets in <strong>Theme settings > Typography</strong>. Choose a smaller preset when several cards sit side by side.</td></tr><tr><td><strong>Background</strong></td><td>Puts a solid panel behind the wording. Turn it on when the text sits over a busy photo and becomes hard to read.</td></tr><tr><td><strong>Background color</strong></td><td>The color of that panel. Pick one with enough contrast against the wording, or the card becomes harder to read than it was without it.<br><em>* Note: Only appears when <strong>Background</strong> is enabled</em></td></tr><tr><td><strong>Corner radius</strong></td><td>How rounded the corners of that panel look. Higher values give a softer shape, 0 leaves the corners square.<br><em>* Note: Only appears when <strong>Background</strong> is enabled</em></td></tr><tr><td><strong>Spacing top/bottom</strong></td><td>Breathing room above and below the wording. Increase it when the text presses against the media or the button.</td></tr></tbody></table>

#### Button <a href="#button" id="button"></a>

| Setting                  | Description                                                                                                                                                                                                                                                                                                                |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Button label**         | The words shoppers click. Leave it empty and no button is shown at all, which leaves the card with nothing to act on.                                                                                                                                                                                                      |
| **Button link**          | Where that click takes shoppers, usually the collection or page the card is about.                                                                                                                                                                                                                                         |
| **Type**                 | <p>How much the button stands out from the card around it.</p><ul><li><strong>Primary</strong>: a solid block of color, for the card you most want clicked.</li><li><strong>Outline</strong>: a bordered style, for supporting cards.</li><li><strong>Link</strong>: plain underlined text, the quietest option.</li></ul> |
| **Open link in new tab** | Loads the destination in a second browser tab, so the store stays open behind it. Useful when the card points somewhere outside your store.                                                                                                                                                                                |
| **Spacing bottom**       | Space left under the button. Increase it when the button sits too close to the edge of the card.                                                                                                                                                                                                                           |

### What changes on the storefront <a href="#what-changes" id="what-changes"></a>

* Uploading a video replaces the picture on the card, so a card cannot show both.
* With **Content position** set to **Overlay image**, readability depends entirely on the photo. Use the overlay opacity or the text background when the photo is busy.
* An empty **Button label** removes the button, but the **Link** on the media can still make the whole card clickable.

### Related pages <a href="#related-pages" id="related-pages"></a>

* [Multi-content](/velare/customize-your-pages/storytelling/multi-content.md): the section this block belongs to
* [Group block - Image](/velare/customize-your-pages/storytelling/multi-content/theme-block-image.md): the simpler picture only block
* [Group block - Video](/velare/customize-your-pages/storytelling/multi-content/theme-block-video.md): use it when the clip needs its own playback settings
* [Colors](/velare/set-up-your-store/colors.md) and [Typography](/velare/set-up-your-store/typography.md): where the schemes and 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/storytelling/multi-content/theme-block-media-with-text.md?ask=<question>&goal=<endgoal>
```

`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.