Image properties

Image URL

The image URL is specified using the image_url parameter. This parameter is optional — you can omit the URL if you want to display only a placeholder or preview.

If you want to display a placeholder without loading the main image, you can omit image_url and use only the placeholder_color or preview parameters.

To load images from assets, use the following URL format: "image_url": "divkit-asset://image.png".

On iOS, you can also specify a specific bundle for loading images using the bundle parameter in the query string: "image_url": "divkit-asset://image.png?bundle=com.example.app".

Supported image formats

DivKit supports various image formats for different platforms:

Basic formats

• PNG - raster images with transparency
• JPEG - raster images with compression
• WebP - modern format with better compression
• GIF - animated images
• SVG - vector images

Animated formats

• Animated WebP - animated images in WebP format
• GIF - classic animated images

SVG image format

DivKit supports SVG image format. You can load SVG files from assets using the standard format:

• "image_url": "divkit-asset://image.svg"

On Android, you can also use the alternative format:

• "image_url": "file:///android_asset/divkit/image.svg"

Image scale

You can set the image scale in the scale parameter:

• fill: Fills all available space. If an image doesn't fit, it gets cropped.
• fit: Fits into the borders, any remaining space will be empty.
• no_scale: The image keeps its original size.
• stretch: The image is stretched to the element size without preserving the aspect ratio.

The position of the image can be changed inside the border of the element using alignment via content_alignment_horizontal and content_alignment_vertical.

Image wrap_content behavior

When using wrap_content with images in DivKit, the component will calculate the appropriate dimensions based on the image's natural size and any constraints provided.

Basic principles

The wrap_content behavior for images follows these principles:

1. When both width and height are set to wrap_content, the image is displayed at its natural dimensions scaled according to the device screen density
2. When one dimension is set to wrap_content and the other has a fixed size, the wrap_content dimension is calculated based on the fixed dimension and the aspect ratio of the image
3. When an aspect ratio is specified, it overrides the natural aspect ratio of the image

Scenarios

Both dimensions use wrap_content

When both width and height are set to wrap_content, the image will be displayed at its natural size:

{
  "type": "image",
  "image_url": "https://example.com/image.png",
  "width": {
    "type": "wrap_content"
  },
  "height": {
    "type": "wrap_content"
  }
}

In this case, the size of the div will be determined by the actual size of the image.

One dimension fixed, one wrap_content

When one dimension is fixed and the other uses wrap_content, the wrap_content dimension is calculated based on the fixed dimension and the image's aspect ratio:

{
  "type": "image",
  "image_url": "https://example.com/image.png",
  "width": {
    "type": "wrap_content"
  },
  "height": {
    "type": "fixed",
    "value": 150
  }
}

In this example, the width will be calculated based on the fixed height (150) and the aspect ratio of the image.

Using aspect ratio

When an aspect ratio is specified, it overrides the natural aspect ratio of the image:

{
  "type": "image",
  "image_url": "https://example.com/image.png",
  "width": {
    "type": "wrap_content"
  },
  "height": {
    "type": "wrap_content"
  },
  "aspect": {
    "ratio": 2
  }
}

In this example, the image will maintain an aspect ratio of 2:1 (width:height), regardless of its natural aspect ratio.

Dynamic resizing

When an image with wrap_content dimensions is loaded asynchronously, the layout will be recalculated once the image is loaded, potentially causing a layout shift. To avoid this, consider using fixed dimensions or a placeholder with the same dimensions as the expected image.

Placeholders

A gray placeholder is displayed before the image is loaded. In place of it, you can insert:

• placeholder_color: A colored solid placeholder.
• preview: An image encoded in base64.
• preview_url: A URL to a placeholder image (supported for GIF images).

If both preview and placeholder_color are specified, preview has priority. For GIF images, preview_url can be used as an alternative to preview.

Image without URL

You can create images without specifying image_url or gif_url. In this case, only the placeholder or preview will be displayed:

{
  "type": "image",
  "width": {
    "type": "fixed",
    "value": 100
  },
  "height": {
    "type": "fixed",
    "value": 100
  },
  "placeholder_color": "#FFCCCCCC"
}

This approach is useful when you need to reserve space for an image that will be loaded later, or when an image is not required but a visual placeholder is needed.

Replacing a placeholder with animation

After the image is loaded, the placeholder will be replaced with the downloaded picture. To add a fade animation effect, specify the appearance_animation parameter:

{
    "type": "image",
    "appearance_animation": {
        "type": "fade",
        "alpha": 0.0,
        "duration": 200.0
    },
    "image_url": ...
}

Image effects

DivKit supports various effects for images:

Blur effect

Applies blur to the image. Supported for PNG, SVG, and WebP formats.

Tint effect

Changes the image color using tinting. Supported for PNG, SVG, and WebP formats.

Combined effects

Multiple effects can be combined to create complex visual results.

Platform-specific features

Connecting image loaders and the bitmap size limitation on Android, as well as loading images from a bundle on iOS, are described in Resources: fonts, images, and video.

Local resources

To work with local images, use the divkit-asset:// scheme:

{
  "type": "image",
  "image_url": "divkit-asset://local_image.png"
}

The divkit-asset:// scheme is supported on Android and iOS. On iOS, the URL can specify the bundle the image is loaded from, see Resources.

Web

On the Web platform, DivKit automatically detects the use of GIF images and displays a warning in the browser console when they are used in the div-image component. This is due to differences in animation behavior between platforms:

• GIF animations on Web are played automatically
• The behavior differs from Android and iOS platforms
• For cross-platform compatibility, it's recommended to consider these differences during development

Image preloading

The preload_required property (in Kotlin DSL — preloadRequired) is deprecated and will be removed in the next major version of DivKit. Do not use it in new templates.

Animated images

DivKit supports displaying animated images:

Animated WebP

WebP format supports animation with better compression compared to GIF.

GIF images

Classic animated image format.

Features

• Animation plays automatically after the image is loaded
• Animation repeat control is supported
• Optimized memory handling for large animations
• Supports preview_url property for displaying a placeholder before GIF image loads

Using preview_url for GIF images

For GIF images, you can use the preview_url property to specify a URL to a placeholder image that will be displayed before the main GIF loads:

{
  "type": "gif",
  "gif_url": "https://example.com/animation.gif",
  "preview_url": "https://example.com/preview.png"
}

GIF image without URL

You can also create a GIF image without specifying gif_url, using only the preview:

{
  "type": "gif",
  "width": {
    "type": "fixed",
    "value": 150
  },
  "height": {
    "type": "fixed",
    "value": 150
  },
  "preview_url": "https://example.com/preview.png"
}

Learn more

You can discuss topics of interest in the DivKit user community in Telegram: https://t.me/divkit_community_en.

DivKit Repository