---
title: Defining image variants
---

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

Image variants are user-defined versions of [page attachments](https://docs.kentico.com/13/managing-website-content/working-with-files/page-attachments.md). You can define each image variant differently so that you have images for various scenarios. For example, you can create image variant definitions for different browser viewports or for various devices such as mobile phones, tablets, desktops, etc.

Each image variant is described by one **image variant definition**. The image variant definition describes what operations need to be applied to page attachments in order to create image variants.

The image operations are [defined by filters](https://docs.kentico.com/13/developing-websites/managing-responsive-images/defining-image-filters.md). How you use the filters in an image variant definition is up to you. For example, you can use multiple filters or use a filter repeatedly in an image variant definition to achieve the desired effect.

By default, no definitions of image variants are included in the system. To add an image variant definition, you need to create a new class in the Xperience project and implement the image variant definition in code.

## Example

### Creating image variant definitions

The following example describes how to create a sample image variant definition for a low resolution image variant. The definition uses the [sample crop filter](https://docs.kentico.com/13/developing-websites/managing-responsive-images/defining-image-filters.md) to modify images.

1. Open your Xperience administration solution in Visual Studio (using the **WebApp.sln** file).
2. Create a new _Class Library_ project in the solution (or reuse an existing custom project), and add the required references.

   - See the [Defining image filters](https://docs.kentico.com/13/developing-websites/managing-responsive-images/defining-image-filters.md) example for detailed instructions on how to create the Class library project.
3. Create a new class under your custom project. For example, name the class _TabletImageVariantDefinition.cs._
4. Add _using_ statements for the following namespaces.

   ```csharp

   using System.Collections.Generic;

   using CMS.DocumentEngine;
   using CMS.ResponsiveImages;

   ```
5. Make the class inherit from the **ImageVariantDefinition** abstract class (available in the _CMS.ResponsiveImages_ namespace).
6. Override the **Identifier** and **Filters** properties of the _ImageVariantDefinition_ class, and implement their functionality.

   - _Identifier_ – the image variant definition identifier. The identifier name cannot start with a number, and can contain only alphanumeric characters or underscores.
   - _Filters_ – a collection of [filters](https://docs.kentico.com/13/developing-websites/managing-responsive-images/defining-image-filters.md) that are used to create the image variant. The order of filters in the collection determines the order in which they are applied to images.

     ```csharp

     public class TabletImageVariantDefinition : ImageVariantDefinition
     {
         // Defines the image variant definition identifier
         public override string Identifier
         {
             get
             {
                 return "Tablet";
             }
         }

         // Defines a set of filters applied to images
         public override IEnumerable<IImageFilter> Filters
         {
             get
             {
                 return new IImageFilter[]
                 {
                     new CropImageFilter(768)
                 };
             }
         }
     }

     ```
7. Register your image variant definition into the system by adding the **RegisterImageVariantDefinition** assembly attribute above the class declaration.

   ```csharp

   // Registers the 'TabletImageVariantDefinition' class within the system
   [assembly: RegisterImageVariantDefinition(typeof(TabletImageVariantDefinition))]

   ```

### Limiting the scope of image variant definitions

By default, image variant definitions are global and can be applied to any image page attachments. When defining an image variant, you can restrict its scope by specifying context information, i.e. a site code name, page type, and node alias path.

To limit the scope of image variant definitions, you need to override and implement the **ContextScopes** property. The property can contain multiple context scopes.

For example, the following code demonstrates how to limit the application of an image variant definition only to articles on one site and news posts on another:

```csharp

// Sets context scopes to restrict application of the image variant definition
public override IEnumerable<IVariantContextScope> ContextScopes
{
    get
    {
        return new[]
        {
        new AttachmentVariantContextScope()
            .OnSite("DancingGoatMvc")
            .Type("DancingGoatMvc.Article")
            .Path("/Articles", PathTypeEnum.Children),

        new AttachmentVariantContextScope()
            .OnSite("MySiteCodeName")
            .Type("Mysite.News")
            .Path("/News", PathTypeEnum.Children)
        };
    }
}

```

You can use the **OnSite**, **Type**, and **Path** methods independently and in any order.

### Adding a variant display name

By default, the image variant display name that appears in the administration interface is the same as the identifier set for the image variant definition (in the **Identifier** property).

To assign a custom display name, you need to [create a new resource string](https://docs.kentico.com/13/multilingual-websites/setting-up-a-multilingual-user-interface/working-with-resource-strings.md). The name of the resource string, i.e. the value in the **Key** field, must be in the following format\*: AttachmentVariant.

With the definition of the image variant prepared, you can use it to [generate image variants](https://docs.kentico.com/13/developing-websites/managing-responsive-images/generating-image-variants.md) for your page attachments.