> For the complete documentation index, see [llms.txt](https://docs.realmacsoftware.com/elements-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.realmacsoftware.com/elements-docs/using-elements/components/content-and-media/image.md). # Image The Image component displays a project resource, custom URL, or CMS image. It supports separate light and dark images, responsive framing, lazy loading, fetch priority, an SVG mask, links, and an optional full-screen lightbox. {% embed url="" %} ### Supported Content and File Types Use Image for bitmap resources such as JPG and PNG. Use the [SVG component](/elements-docs/using-elements/components/content-and-media/svg.md) when the vector artwork itself needs fill or stroke styling. ### How to Use Image You’ll find Image under **Media** in the Components list. 1. Drag **Image** onto the page. 2. Choose Resource, Custom, or CMS. 3. Select or enter both Light and Dark sources if needed. 4. Add alternative text or complete the image metadata in Resources. 5. Configure file sizing, loading, aspect ratio, and optional lightbox or mask. ### Component Settings #### Image **Type** * **Resource** — Uses an image stored in the project. This is the default. * **Custom** — Uses an absolute URL or site-relative path. * **CMS** — Uses a CMS field expression. **Mode** switches between Light and Dark while choosing the source. Light is selected by default. The dark image is shown automatically when the visitor’s browser or operating system is set to dark mode (`prefers-color-scheme: dark`). If no dark image is set, the light image is used everywhere. Custom mode displays **Source**. CMS mode displays **Field**, which defaults to `{{item.image.src}}`. Both modes provide **Alt** text. The Field value must be a Twig expression that outputs the image's URL, like the default `{{item.image.src}}`. Typing a front matter key on its own (for example `image`) won't work — wrap it as an expression, e.g. `{{item.image}}` if your front matter stores the URL directly. {% hint style="info" %} CMS images show a placeholder while editing. Preview or publish the page to see the resolved CMS image. {% endhint %} For Custom and CMS sources, **Width** and **Height** define the intrinsic image size and default to 1280 × 720. Display size is controlled separately under Sizing. For Resource images: * **Original** — Exports the original resource size. This is the default behaviour. * **Custom** — Exports a resized file. File Size defaults to 400 pixels. {% hint style="warning" %} Custom-sized resources are exported at twice the entered width for Retina displays. A File Size of 400 pixels creates an 800-pixel export. {% endhint %} **Image Protection** discourages simple right-click downloading and is off by default. It cannot prevent visitors from retrieving an image already delivered to their browser. **Lazy Loading** adds the browser’s `loading="lazy"` attribute and is off by default. Avoid lazy loading a prominent image near the top of the page. **Fetch Priority** offers Auto, High, or Low and defaults to Auto. {% hint style="success" %} Optimised image dimensions and appropriate lazy loading can improve page performance without reducing visible quality. {% endhint %}
Image Inspector controls for source, sizing, protection, lazy loading, and fetch priority

The Image group controls the source file and loading behaviour.

#### Mask **SVG** selects the mask resource. Black or opaque areas reveal the image. **Size** offers Contain, Cover, or Fill and defaults to Contain. #### Lightbox **Enable** opens the image full-screen when clicked and is off by default. When enabled, **Color** defaults to Black, **Opacity** to 50%, and **Blur** to 0 pixels.
Image Lightbox controls for backdrop colour, opacity, and blur

Lightbox backdrop controls.

#### Link Set **To** to link the image. Avoid enabling both a Link and Lightbox because visitors need one clear click action. #### Aspect Ratio **Aspect Ratio** * **Auto** — Uses the image’s natural ratio. This is the default. * **Wide** — Uses 16:9. * **Tall** — Uses 4:5. * **Custom** — Uses an `x/y` value; the default is `7/5`. When the ratio is not Auto, **Object Fit** offers Fill, Contain, Cover, None, or Scale Down and defaults to Cover, and **Position** chooses the focal point from the centre, edges, or corners and defaults to Centre.
Image Aspect Ratio controls with object fit and position options

Aspect Ratio controls the image frame and crop.

Image Inspector showing custom aspect-ratio settings

A custom aspect ratio can use any valid x/y value.

### A Note About Image Protection Browsers must download images before displaying them, so no front-end setting can make an image impossible to retrieve. Image Protection only discourages casual saving. Watermark valuable images and export them at an appropriate web resolution. ### Accessibility Describe informative images with concise alternative text. Leave alt text empty only for purely decorative images, and avoid repeating an adjacent caption word for word. ### Related Components * [Gallery](/elements-docs/using-elements/components/content-and-media/gallery.md) — Displays a folder of media in a grid and lightbox. * [SVG](/elements-docs/using-elements/components/content-and-media/svg.md) — Displays and recolours vector artwork. * [Mask](/elements-docs/using-elements/components/styling-and-effects/mask.md) — Provides more advanced masking options for wrapped content. | Common Control | Description | | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- | | [Link](/elements-docs/using-elements/components/common-controls/link.md) | Link to a page, resource, anchor, email address, or website. | | [Layout](/elements-docs/using-elements/components/common-controls/layout.md) | Control positioning, stacking, visibility, overflow, and isolation. | | [Sizing](/elements-docs/using-elements/components/common-controls/sizing.md) | Set width, height, and responsive size constraints. | | [Spacing](/elements-docs/using-elements/components/common-controls/spacing.md) | Add responsive margin and padding. | | [Typography & Text Styles](/elements-docs/using-elements/components/common-controls/typography-and-text-styles.md) | Control fonts, text spacing, decoration, colour, and semantic wrappers. | | [Backgrounds](/elements-docs/using-elements/components/common-controls/backgrounds.md) | Apply colour, image, gradient, SVG, video, and hover backgrounds. | | [Transitions](/elements-docs/using-elements/components/common-controls/transitions.md) | Choose what animates and set its timing curve, duration, and delay. | | [Effects](/elements-docs/using-elements/components/common-controls/effects.md) | Apply shadows, opacity, and hover effects. | | [Filters](/elements-docs/using-elements/components/common-controls/filters.md) | Apply blur, brightness, saturation, shadow, and backdrop effects. | | [Transforms](/elements-docs/using-elements/components/common-controls/transforms.md) | Scale, rotate, move, and skew components. | | [Borders](/elements-docs/using-elements/components/common-controls/borders.md) | Set border style, colour, opacity, width, radius, and hover states. | | [Advanced](/elements-docs/using-elements/components/common-controls/advanced.md) | Add CSS classes and IDs, or change supported HTML tags. | --- # 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://docs.realmacsoftware.com/elements-docs/using-elements/components/content-and-media/image.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.