Image properties

Image URL

The image URL must be specified using the required image_url parameter. If you want to display a placeholder, but you don't have a valid URL, you can specify "image_url": "empty://".

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

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"

Platform-specific features

iOS

On iOS, to restrict access to resources, all divkit asset images must start with the 'divkit.' prefix. For example, if you use "image_url": "divkit-asset://image.png", the image must be named divkit.image.png in your app's main bundle.

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 will retain its original 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.

If both preview and placeholder_color are specified, preview has a priority.

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": ...
}

Learn more

Follow DivKit news in the Telegram channel: http://t.me/divkit_news

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

DivKit Repository