--- metadata: - name: generator content: Diplodoc Platform v5.50.3 alternate: - https://divkit.tech/docs/en/concepts/image.md - https://divkit.tech/docs/ru/concepts/image.md --- > **Documentation Index:** Fetch the complete configuration index at https://divkit.tech/docs/en/llms.txt # Image properties ## Image URL {#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"`. 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 {#supported-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 {#svg} 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 {#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`. ![](../_images/create-card/scale-types-screenshot.png =200x) {% cut "View an interactive example" %} {% endcut %} ## Image wrap_content behavior {#wrap-content} 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: ```json { "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: ```json { "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: ```json { "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 {#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`. ![](../_images/create-card/placeholders-no-code.png =300x) {% cut "View an interactive example" %} {% endcut %} ## Replacing a placeholder with animation {#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: ```json translate=no { "type": "image", "appearance_animation": { "type": "fade", "alpha": 0.0, "duration": 200.0 }, "image_url": ... } ``` ## Image effects {#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 {#platform-specific} ### iOS {#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. #### Multiple bundle support Starting from version 32.39.0, iOS supports specifying a specific bundle for loading images using the `bundle` parameter in the URL: ```json { "type": "image", "image_url": "divkit-asset://image.png?bundle=com.example.app" } ``` This feature is useful in modular architectures or when using multiple bundles in an application. On other platforms (Android, Web), the `bundle` parameter is ignored. ### Android {#android} #### Image loader support DivKit for Android supports popular image loading libraries: - **Coil** - modern image loader for Kotlin - **Glide** - traditional image loader Both loaders support all image formats and effects, including animated WebP and GIF. ### Web {#web} #### Image handling features 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 #### Local resources To work with local images, use the `divkit-asset://` scheme: ```json { "type": "image", "image_url": "divkit-asset://local_image.png" } ``` #### Bitmap size limitation {#bitmap-size-limit} To prevent crashes when loading large images and GIF files, DivKit automatically limits the bitmap size. This feature is enabled by default and helps avoid memory issues on devices. **How the limitation works:** - The maximum bitmap size is determined by the maximum screen resolution of the device - Images exceeding this size are automatically scaled down - For SVG images, a separate limitation mechanism is applied - The feature is supported by all popular image loading libraries (Coil, Glide, Picasso) **Configuring the limitation:** Bitmap size limitation is enabled by default. If you need to disable this feature (for example, when working with very large images), you can configure it in the image loader implementation: ```kotlin // Example for CoilDivImageLoader val imageLoader = CoilDivImageLoader( context = context, limitImageBitmapSizeEnabled = false // Disable limitation ) ``` {% note warning %} Disabling bitmap size limitation may lead to application crashes when working with very large images. Use this setting with caution. {% endnote %} ## Animated images {#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: ```json { "type": "gif", "gif_url": "https://example.com/animation.gif", "preview_url": "https://example.com/preview.png" } ``` This property is supported on all platforms (Android, iOS, Web). {% note warning %} **Cross-platform differences for GIF images:** On the Web platform, GIF animations are played automatically, but this behavior differs from other platforms (Android/iOS). When using GIF images in the `div-image` component on the Web platform, a warning is displayed in the console about the behavior mismatch between platforms. {% endnote %} ## Learn more {#troubleshooting} You can discuss topics of interest in the DivKit user community in Telegram: [https://t.me/divkit_community_en](https://t.me/divkit_community_en). [DivKit Repository](https://github.com/divkit/divkit)