Customization

The extension element is a data block that is used to change the behavior and display of elements. You can add an extension to any element.

Additional logic is described in the extension handler DivExtensionHandler.

Available extensions

ID	Description	Source code
`pinch-to-zoom`	Increases the element.	Android iOS
`lottie`	Connects Lottie animations to gif-image.	Android iOS Web
`input_autocorrection`	Controls text autocorrection in input elements (iOS only).	iOS
`aspect-correction`	Automatically crops images in div-image to the expected aspect ratio (iOS only).	iOS
`rasterize`	Fixes offscreen rendering issues in overlap containers (iOS only).	iOS
`blur`	Adds a blur effect to the element (iOS only).	iOS
`liquid_glass`	Adds the Liquid Glass effect to the element (iOS 26 and later only).	iOS
`backdrop-effect`	Applies complex graphical effects to the element background: blur, refraction, color adjustment, and rim highlight (Android only).	Android

Connection

Note

This section uses the Lottie extension as an example.

Android

iOS

Web

build.gradle

dependencies {
    implementation "com.yandex.div:div-pinch-to-zoom:${versions.divkit}"
    implementation "com.airbnb.android:lottie:${versions.lottie}"
    implementation "com.yandex.div:div-lottie:${versions.lottie}"
}

In the code:

val pinchToZoomConfiguration = DivPinchToZoomConfiguration.Builder(this)
    .host(window)
    .dimColor(0xFF808080.toInt())
    .build()
val rawResProvider = object : DivLottieRawResProvider {
    override fun provideRes(url: String): Int? {
        if (url == "res://love") return R.raw.love_anim
        return null
    }
    override fun provideAssetFile(url: String): String? {
        if (url == "asset://banana") return "lottie/lottie_1.json"
        return null
    }
}
val divConfiguration = DivConfiguration.Builder(DefaultDivImageLoader(Container.imageManager))
    .experimentConfig(experimentConfig)
    .actionHandler(actionHandler)
    .divLogger(logger)
    .extension(DivPinchToZoomExtensionHandler(pinchToZoomConfiguration))
    .extension(DivLottieExtensionHandler(rawResProvider))
    .build()
val divContext = DivContext(baseContext = this, configuration = divConfiguration)
divView = DivView(divContext)

Extension handlers must comply with the DivExtensionHandler protocol.

To connect the handler, pass it to DivBlockModelingContext:

DivBlockModelingContext(
  ...
  extensionHandlers: [
    PinchToZoomExtensionHandler(overlayView: rootView),
    SomeExtensionHandler()
  ]
)

import { lottieExtensionBuilder } from '@divkitframework/divkit/client';
import Lottie from 'lottie-web/build/player/lottie';

const map = new Map();

map.set('lottie', lottieExtensionBuilder(Lottie.loadAnimation));

render({
    id: 'test',
    target: element,
    json: {},
    extensions: map
});

An example of a connected extension is available in the repository.

Lottie in an animated gif image

To connect the animation to a gif image, fill in the extensions array:

{
  "extensions": [
    {
      "id": "lottie",
      "params": {
        "lottie_url": "https://assets9.lottiefiles.com/packages/lf20_edpg3c3s.json",
        "repeat_count": 3,
        "repeat_mode": "restart"
      }
    }
  ]
}

Note

repeat_count parameter behavior

repeat_count: 0 — animation plays once
repeat_count: 1 — animation plays twice
repeat_count: N — animation plays N+1 times
repeat_count: -1 — infinite looping

Parameters	Description
`id`	Extension ID.
`lottie_url`	Required URL to Lottie JSON if the `lottie_json` parameter isn't specified. It can work according to the `asset:{address}` or `res:{address}` schemes for embedded resources. Resource binding in these schemes occurs via the `DivLottieRawResProvider` dependency that is passed to `DivLottieExtensionHandler`. When using unsupported URL schemes (not http/https/file/res), animation preloading will be skipped with an error logged.
`lottie_json`	Required parameter if `lottie_url` isn't specified. Contains Lottie JSON.
`repeat_count`	The number of animation repetitions. Use the `-1` value for an infinite number of repetitions.
`repeat_mode`	The action after the animation ends. It can have the values: `restart`: Animation restarts. `reverse`: Animation is displayed frame-by-frame in reverse order.
`min_frame`	The minimum frame from which the animation starts. Used for complex cyclic playback scenarios.
`is_playing`	Controls automatic animation playback during initialization. If set to `false`, the animation won't start automatically. Default: `true`.

Input autocorrection control

To control text autocorrection in input elements on iOS, use the input_autocorrection extension:

{
  "extensions": [
    {
      "id": "input_autocorrection",
      "params": {
        "enabled": false
      }
    }
  ]
}

Parameters	Description
`id`	Extension ID.
`enabled`	Controls whether autocorrection is enabled for the input field. Set to `false` to disable autocorrection.

Automatic image aspect ratio correction

To automatically crop images in div-image to the expected aspect ratio, use the aspect-correction extension (iOS only):

{
  "extensions": [
    {
      "id": "aspect-correction",
      "params": {
        "aspect_tolerance": 0.001
      }
    }
  ]
}

Parameters	Description
`id`	Extension ID.
`aspect_tolerance`	Aspect ratio deviation tolerance (optional). If the actual aspect ratio differs from the expected one by less than this value, cropping is not applied. Default: 0.001.

Features:

Images are cropped centrally when there is a significant deviation from the expected aspect ratio
If the actual aspect ratio is less than expected - cropped by height
If the actual aspect ratio is greater than expected - cropped by width
Caching of processed images is supported for performance optimization

Integration on iOS:

DivBlockModelingContext(
  ...
  extensionHandlers: [
    AspectCorrectionExtensionHandler(aspectTolerance: 0.001)
  ]
)

Rasterization for fixing offscreen rendering

To fix offscreen rendering issues in overlap containers, use the rasterize extension (iOS only):

{
  "extensions": [
    {
      "id": "rasterize"
    }
  ]
}

Parameters	Description
`id`	Extension ID.

Features:

Applies rasterization to blocks via layer.shouldRasterize = true
Uses UIScreen.main.scale for optimal quality
Solves offscreen rendering issues in overlap containers

Integration on iOS:

DivBlockModelingContext(
  ...
  extensionHandlers: [
    RasterizeExtensionHandler()
  ]
)

Blur effect

To add a blur effect to an element, use the blur extension (iOS only):

{
  "extensions": [
    {
      "id": "blur",
      "params": {
        "intensity": 0.5
      }
    }
  ]
}

Specify exactly one of the style and intensity parameters. If both parameters are specified, or
if neither is specified, DivKit reports a block modeling error and does not apply the blur.

Parameters	Description
`id`	Extension ID.
`style`	Blur effect style at full system intensity. This parameter cannot be used together with `intensity`. Available values: `extra_light` — extra light `regular` — regular `prominent` — prominent `system_ultra_thin_material` — ultra thin material `system_ultra_thin_material_light` — ultra thin material (light variant) `system_ultra_thin_material_dark` — ultra thin material (dark variant) `system_thin_material` — thin material `system_thin_material_light` — thin material (light variant) `system_thin_material_dark` — thin material (dark variant) `system_material` — material `system_material_light` — material (light variant) `system_material_dark` — material (dark variant) `system_thick_material` — thick material `system_thick_material_light` — thick material (light variant) `system_thick_material_dark` — thick material (dark variant) `system_chrome_material` — chrome material `system_chrome_material_light` — chrome material (light variant) `system_chrome_material_dark` — chrome material (dark variant)
`intensity`	Intensity of the regular system blur in the `0...1` range. Values outside the range are clamped. This parameter cannot be used together with `style`. It controls interpolation between no blur and the regular system blur; it does not specify a blur radius.

Features:

Uses iOS system blur effects (UIBlurEffect)
Supports either a system style at full intensity or configurable regular blur intensity using
UIKit effect interpolation
Supports both basic styles and material styles with variants for light and dark themes
Applied to the entire element to which the extension is added

Integration on iOS:

DivBlockModelingContext(
  ...
  extensionHandlers: [
    BlurExtensionHandler()
  ]
)

Liquid Glass effect

To add the Liquid Glass effect to the element, use the liquid_glass extension (iOS only):

{
  "extensions": [
    {
      "id": "liquid_glass",
      "params": {
        "style": "regular",
        "is_interactive": true,
        "tint_color": "#80FF1744",
        "corner_style": {
          "type": "capsule",
          "max_radius": 16
        },
        "ui_style_variable": "ui_style"
      }
    }
  ]
}

The extension works on iOS 26 and later. On earlier versions, the element is rendered without the effect and the layout stays the same.

Parameters	Description
`id`	Extension ID.
`is_enabled`	Enables the effect. If set to `false`, the element is rendered without it, and its size and position stay the same. Useful for toggling the effect with an expression. By default: `true`.
`style`	Required parameter. Effect style. Available values: `regular`: Regular glass. `clear`: Clear glass.
`is_interactive`	Enables the interactive behavior of the effect: the glass reacts to a press. Optional parameter.
`tint_color`	Tint color applied to the effect. Optional parameter.
`corner_style`	Corner rounding of the effect. Optional parameter. If omitted, the system chooses the rounding. Available values of the `type` parameter: `capsule`: Corners are rounded into a capsule and scale with the element size. The optional `max_radius` parameter clamps the radius. `corners`: Fixed radii set by the optional `top_left`, `top_right`, `bottom_left`, and `bottom_right` parameters. A corner without a radius isn't rounded.
`ui_style_variable`	Name of the variable that `light` or `dark` is written to. Optional parameter. The effect resolves the interface style from the content beneath it, so this style may differ from the style of the card. Use the variable to adjust the color of the content placed on top of the glass.

How it works:

The element is wrapped into a UIVisualEffectView with UIGlassEffect, so the background of the element itself is drawn on top of the effect. Don't set an opaque background on the element.
All parameters support expressions, including is_enabled and style.
If style is missing or has an invalid value, DivKit reports a block modeling error and doesn't apply the effect.

Integration on iOS:

DivBlockModelingContext(
  ...
  extensionHandlers: [
    LiquidGlassExtensionHandler()
  ]
)

Example:

Card with several variants of the effect

{
  "templates": {
    "glass_label": {
      "type": "text",
      "font_size": 15,
      "font_weight": "medium",
      "text_alignment_horizontal": "center",
      "text_color": "#FFFFFFFF",
      "width": {
        "type": "match_parent"
      }
    }
  },
  "card": {
    "log_id": "liquid_glass_sample",
    "variables": [
      {
        "name": "is_enabled",
        "type": "boolean",
        "value": true
      },
      {
        "name": "ui_style",
        "type": "string",
        "value": "unknown"
      }
    ],
    "states": [
      {
        "state_id": 0,
        "div": {
          "type": "container",
          "orientation": "vertical",
          "height": {
            "type": "match_parent"
          },
          "paddings": {
            "left": 16,
            "right": 16,
            "top": 24,
            "bottom": 24
          },
          "background": [
            {
              "type": "gradient",
              "angle": 45,
              "colors": [
                "#FFFF3D00",
                "#FF00E676",
                "#FF2979FF"
              ]
            }
          ],
          "items": [
            {
              "type": "container",
              "orientation": "vertical",
              "content_alignment_vertical": "center",
              "height": {
                "type": "fixed",
                "value": 56
              },
              "margins": {
                "bottom": 16
              },
              "paddings": {
                "left": 20,
                "right": 20
              },
              "items": [
                {
                  "type": "glass_label",
                  "text": "clear + tint_color"
                }
              ],
              "extensions": [
                {
                  "id": "liquid_glass",
                  "params": {
                    "style": "clear",
                    "tint_color": "#80FF1744",
                    "corner_style": {
                      "type": "capsule",
                      "max_radius": 16
                    }
                  }
                }
              ]
            },
            {
              "type": "container",
              "orientation": "vertical",
              "content_alignment_vertical": "center",
              "height": {
                "type": "fixed",
                "value": 56
              },
              "margins": {
                "bottom": 16
              },
              "paddings": {
                "left": 20,
                "right": 20
              },
              "items": [
                {
                  "type": "glass_label",
                  "text": "is_enabled = @{is_enabled}"
                }
              ],
              "extensions": [
                {
                  "id": "liquid_glass",
                  "params": {
                    "style": "regular",
                    "is_enabled": "@{is_enabled}",
                    "corner_style": {
                      "type": "corners",
                      "top_left": 4,
                      "top_right": 24,
                      "bottom_left": 24,
                      "bottom_right": 4
                    }
                  }
                }
              ]
            },
            {
              "type": "container",
              "orientation": "vertical",
              "paddings": {
                "left": 16,
                "right": 16,
                "top": 16,
                "bottom": 16
              },
              "border": {
                "corner_radius": 16
              },
              "background": [
                {
                  "type": "solid",
                  "color": "#FF101010"
                }
              ],
              "items": [
                {
                  "type": "container",
                  "orientation": "vertical",
                  "content_alignment_vertical": "center",
                  "height": {
                    "type": "fixed",
                    "value": 56
                  },
                  "paddings": {
                    "left": 20,
                    "right": 20
                  },
                  "items": [
                    {
                      "type": "glass_label",
                      "text": "over dark content"
                    }
                  ],
                  "extensions": [
                    {
                      "id": "liquid_glass",
                      "params": {
                        "style": "regular",
                        "ui_style_variable": "ui_style",
                        "corner_style": {
                          "type": "capsule"
                        }
                      }
                    }
                  ]
                },
                {
                  "type": "text",
                  "text": "ui_style = @{ui_style}",
                  "font_size": 13,
                  "text_color": "#FFFFFFFF",
                  "margins": {
                    "top": 8
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

Background effects

To apply graphical effects to an element background, use the backdrop-effect extension (Android only):

{
  "extensions": [
    {
      "id": "backdrop-effect",
      "params": {
        "blur_radius": 10.0,
        "refraction_height": 5.0,
        "refraction_strength": 0.5,
        "chromatic_aberration": 0.3,
        "brightness": 1.2,
        "contrast": 1.1,
        "saturation": 0.9,
        "rim_highlight_angle": 45.0,
        "rim_highlight_fade": 0.5,
        "corner_radius": 16.0,
        "backdrop_scope": "card"
      }
    }
  ]
}

Parameters	Description
`id`	Extension ID.
`blur_radius`	Background blur radius in pixels. Optional parameter.
`refraction_height`	Refraction effect height. Optional parameter.
`refraction_strength`	Refraction effect strength (from 0.0 to 1.0). Optional parameter.
`chromatic_aberration`	Chromatic aberration strength for refraction effect (from 0.0 to 1.0). Optional parameter.
`brightness`	Background brightness coefficient. Value 1.0 means no change. Optional parameter.
`contrast`	Background contrast coefficient. Value 1.0 means no change. Optional parameter.
`saturation`	Background saturation coefficient. Value 1.0 means no change. Optional parameter.
`rim_highlight_angle`	Light angle for rim highlight in degrees. Optional parameter.
`rim_highlight_fade`	Rim highlight fade coefficient (from 0.0 to 1.0). Optional parameter.
`corner_radius`	Corner radius for all corners in pixels. Optional parameter.
`corner_radii`	Array of 4 values for individual corner radii [topLeft, topRight, bottomRight, bottomLeft]. Optional parameter.
`backdrop_scope`	Background search area for the effect. Optional parameter, default is `"card"`. Available values: `"card"` — background search is limited to the nearest `Div2View` ancestor (current card). Default behavior. `"window"` — background search extends to the entire application window. Allows capturing background outside the current card, including neighboring `Div2View`s and native host views. Requires Android 13 (API 33) and above. On older Android versions, the value automatically degrades to `"card"`. Warning Performance when using `backdrop_scope: "window"` The window capture mode requires redrawing the entire view tree on each effect invalidation, which can be resource-intensive. Use this mode only when you need to capture background outside the current card.
`backdrop_id`	ID of a specific view to capture the background from. If specified together with `backdrop_scope: "window"`, the tag search occurs across the entire window. If not specified, all window content visually beneath the element is captured. Optional parameter.

Features:

On Android 13+ (Tiramisu), RenderNode is used for optimal performance
On older Android versions, Canvas is used to capture the background
The extension automatically tracks changes in the background view position and state (scroll, layout, draw)
Supports two rim highlight variants: plain (Plain) and with reflection (Reflection) for Android 13+
The effect is correctly applied even to elements without an explicitly set background parameter
An unrecognized backdrop_scope value results in a parsing error and disables the effect

Integration on Android:

val backdropEffectHandler = BackdropEffectExtensionHandler()
val divConfiguration = DivConfiguration.Builder(imageLoader)
    .extension(backdropEffectHandler)
    .build()
val divContext = DivContext(baseContext = this, configuration = divConfiguration)

For programmatic effect configuration, use BackdropEffectDrawable:

val backdropDrawable = BackdropEffectDrawable()
backdropDrawable.setBlurEffect(radius = 10f)
backdropDrawable.setRefractionEffect(height = 5f, strength = 0.5f, chromaticAberration = 0.3f)
backdropDrawable.setColorAdjustment(brightness = 1.2f, contrast = 1.1f, saturation = 0.9f)
backdropDrawable.setRimHighlightEffect(angle = 45f, fade = 0.5f)
backdropDrawable.setCornerRadius(radius = 16f)
// Or for individual radii:
backdropDrawable.setCornerRadii(floatArrayOf(16f, 8f, 8f, 16f))

Example usage with background capture outside the card:

Example with backdrop_scope: window

{
  "extensions": [
    {
      "id": "backdrop-effect",
      "params": {
        "blur_radius": 15.0,
        "backdrop_scope": "window"
      }
    }
  ]
}

This example blurs the entire application window background beneath the element, including content outside the current card.

Learn more

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

DivKit Repository

Was the article helpful?

visibility-action

FAQ