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
.
View an interactive example
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:
- 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 - When one dimension is set to
wrap_content
and the other has a fixed size, thewrap_content
dimension is calculated based on the fixed dimension and the aspect ratio of the image - 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.
View an interactive example
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