---
title: Image variants basics
---

> Agent instructions:
> **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown.
>
> - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version.
> - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt).

## Understanding image variants

An **image variant** is a **resized and cropped** version of your original image that follows your company's graphic design guidelines. Your developers ensure that the image stays responsive and on brand across different marketing channels or in your marketing campaigns.

For example:

- A wide **hero banner** might use a landscape variant.
- A **thumbnail** might use a square variant.
- A **social media card** might need yet another size and ratio.

You don't need to create these versions yourself. Once configured, Xperience automatically generates them from the **primary optimized image** you upload into [Content hub](https://docs.kentico.com/guides/digital-marketing/xperience-essentials/manage-content-hub-essentials.md).

> **Info:** Each project can have its own set of image variants, depending on the design and channel requirements. Your project's UX and graphic designers work with developers to decide which aspect ratios and sizes are needed, and they set up the rules in advance.
>
> That means you don't need to create multiple sizes of your images manually, or worry about compression settings under time pressure – you can leave the basic optimization to [AIRA](https://docs.kentico.com/documentation/business-users/aira.md). If you ever find a particular variant that isn't currently available, you can ask your administrator or developer to create one for you. You're not restricted in how many variants your project can support.

## Why image variants matter, and what they do

Image variants are more than just a matter of convenience. When you upload your image assets into Content hub, _AIRA_ automatically transforms them, giving you several image variants to choose from. But what do you do with these variants once they're ready?

Image variants, in short, help you:

- Keep your images looking great across different contexts.
- Avoid stretched, cut-off, or pixelated visuals.
- Ensure a consistent look across pages, devices, and channels.
- Save time by letting the system handle most of the resizing and cropping for you.

## Where you choose a variant

Administrators and developers configure the image variants available in your project. Who selects a variant depends on where you place the image:

- In rich text, you choose the variant. When you insert an image into any [rich text field](https://docs.kentico.com/documentation/business-users/rich-text-editor.md), select an option from the **Image variant** drop-down list. This selection requires no extra developer setup.
- In a widget, you choose the variant when the widget has a dedicated property. Developers can give a [widget](https://docs.kentico.com/documentation/business-users/website-content/widgets-and-page-builder.md) a [property](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/widgets-for-page-builder/widget-properties.md) for selecting a variant. In the Kbank demo site, for example, the _Image_ widget includes a _Fixed image variant_ property. If a frequently used widget needs variant selection, ask your developers to add this property.
- Everywhere else, developers configure display rules based on visitor screen sizes and page layouts to serve the appropriate image. You do not need to track or select variants for these locations.

To insert a specific variant into rich text:

1. In the rich text editor toolbar, select **Insert image** (or choose **Select existing** if the button shows a
   menu).
2. Select your desired image from the asset library.
3. In the **Image variant** drop-down list, select the preferred variant.
4. Select **Insert** to place the image into your content.

If you don't see the list, ask your administrators to define image variants. For more details, see how to [insert image variants](https://docs.kentico.com/documentation/business-users/rich-text-editor.md#insert-image-variants).