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
`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": {
        "style": "regular"
      }
    }
  ]
}

Parameters

Description

id

Extension ID.

style

Blur effect style. 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)

Features:

Uses iOS system blur effects (UIBlurEffect)
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()
  ]
)

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
      }
    }
  ]
}

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.

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+

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))

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