--- metadata: - name: generator content: Diplodoc Platform v5.70.0 alternate: - https://divkit.tech/docs/en/concepts/extensions/backdrop-effect.md - https://divkit.tech/docs/ru/concepts/extensions/backdrop-effect.md - href: https://divkit.tech/docs/en/concepts/extensions/backdrop-effect.md type: text/markdown title: Markdown version - href: https://divkit.tech/docs/en/llms.txt?revision=r22102947 rel: describedby --- > **Documentation Index:** Fetch the complete configuration index at https://divkit.tech/docs/en/llms.txt?revision=r22102947 # Backdrop effects The `backdrop_effect` extension applies graphical effects to the content located under the element: blur, refraction, color adjustment, and rim highlight (Android only): ```json translate=no { "extensions": [ { "id": "backdrop_effect", "params": { "blur": { "radius": 8 }, "refraction": { "height": 12, "strength": 24, "chromatic_aberration": true }, "color_adjustment": { "brightness": 0.1, "contrast": 1.1, "saturation": 1.5 }, "rim_highlight": { "type": "specular", "width": 1, "alpha": 0.8, "color": "#80FFFFFF", "angle": 45, "falloff": 1 }, "backdrop_scope": "card" } } ] } ``` Each effect is described by a nested object. If the object of an effect isn't specified, the effect isn't applied. ## Parameters {#params} All parameters are optional. The extension parameters don't support expressions. #| || **Parameters** | **Description** || || `id` | Extension ID. || || `backdrop_id` | ID (`id`) of the element whose content is used as the backdrop for the effect. It can be a parent element of any level or another element of the card. If the parameter isn't specified, the backdrop is defined by the `backdrop_scope` parameter. || || `backdrop_scope` | Backdrop search area: `card` or `window`. Default: `card`. See [Backdrop search area](#backdrop-scope). || || `blur` | Backdrop blur. See [Blur](#blur). || || `refraction` | Backdrop refraction near the element edges. See [Refraction](#refraction). || || `color_adjustment` | Backdrop color adjustment. See [Color adjustment](#color-adjustment). || || `rim_highlight` | Highlight of the element edges. See [Rim highlight](#rim-highlight). || |# The corner rounding of the effect is taken from the `border` property of the element: `corner_radius` or `corners_radius`. ### Backdrop search area {#backdrop-scope} The `backdrop_scope` parameter accepts the values: - `card`: The backdrop is searched for within the card the element belongs to. If the `backdrop_id` parameter isn't specified, the whole card is the backdrop. - `window`: The backdrop is searched for in the entire application window: - If the `backdrop_id` parameter is specified, the element with this ID is searched for in the entire window, including other cards and application views with the same tag. - If the `backdrop_id` parameter isn't specified, the backdrop is everything rendered in the window under the element, including neighboring cards and native application views. This mode requires Android 13 (API 33) and above. On older Android versions, the value works as `card`. An unrecognized `backdrop_scope` value results in a parameter parsing error, and the effect isn't applied. {% note warning %} **Performance when using `backdrop_scope: "window"`** If the `backdrop_id` parameter isn't specified, the content of the entire window is rendered again on each update of the effect, which can be resource-intensive. Use this mode only when you need to capture the backdrop outside the current card. {% endnote %} ### Blur {#blur} #| || **`blur` parameters** | **Description** || || `radius` | Backdrop blur radius in dp. Default: `0` (no blur). || |# ### Refraction {#refraction} #| || **`refraction` parameters** | **Description** || || `height` | Width of the zone along the element edges where the backdrop is refracted, in dp. Default: `0` (no refraction). || || `strength` | Refraction strength: the largest displacement of the backdrop in the refraction zone, in dp. Default: `0`. || || `chromatic_aberration` | Enables chromatic aberration: color fringes in the refraction zone. Default: `false`. || |# ### Color adjustment {#color-adjustment} #| || **`color_adjustment` parameters** | **Description** || || `brightness` | Backdrop brightness change. The `0` value means no change, positive values make the backdrop lighter. Default: `0`. || || `contrast` | Backdrop contrast coefficient. The `1` value means no change. Default: `1`. || || `saturation` | Backdrop saturation coefficient. The `1` value means no change, the `0` value means grayscale. Default: `1`. || |# ### Rim highlight {#rim-highlight} The highlight kind is set by the `type` field: - `specular`: A highlight of the specified color whose brightness depends on the light direction. - `ambient`: A white highlight of the edges that face the light source. #| || **`rim_highlight` parameters** | **Description** || || `type` | Required parameter. Highlight kind: `specular` or `ambient`. An unrecognized value results in a parameter parsing error, and the effect isn't applied. || || `width` | Highlight width in dp. Default: `0.5`. || || `alpha` | Highlight opacity from `0` to `1`. Default: `1`. || || `angle` | Light direction angle in degrees. Default: `45`. || || `color` | Highlight color (`specular` only). Default: `#80FFFFFF`. || || `falloff` | Exponent of the highlight falloff as the edge deviates from the light direction (`specular` only). Default: `1`. || || `intensity` | Highlight brightness from `0` to `1` (`ambient` only). Default: `0.4`. || |# ## How it works {#behavior} - The effect is displayed under the element's own background. For the effect to be visible, the element background (`background`) must be translucent or absent. - Refraction and color adjustment are available on Android 13 (API 33) and above. On older Android versions, only the blur and the rim highlight are applied, and the highlight is uniform: `angle` and `falloff` are ignored. - The captured backdrop is updated on layout changes and on scroll. If the backdrop content changes in another way, for example, when it is a video or an animation, the effect may show an outdated image. To report such changes, pass a `BackdropWatcher` to the handler. - The effect is resource-intensive: the backdrop is rendered again on each update. Apply it to small and mostly static elements. - If `backdrop_scope` is `window` and the `backdrop_id` parameter isn't specified, the elements rendered on top of the element with the effect are hidden while the backdrop is captured. Because of this, their animations may pause, for example. ## Connection {#connect} build.gradle ```groovy translate=no dependencies { implementation "com.yandex.div:backdrop-effect:${versions.divkit}" } ``` In the code: ```kotlin translate=no val backdropEffectHandler = BackdropEffectExtensionHandler() val divConfiguration = DivConfiguration.Builder(imageLoader) .extension(backdropEffectHandler) .build() val divContext = Div2Context(baseContext = this, configuration = divConfiguration) ``` To report backdrop changes that the extension doesn't track itself, pass a `BackdropWatcher` to the handler: ```kotlin translate=no val backdropEffectHandler = BackdropEffectExtensionHandler( backdropWatcher = object : BackdropWatcher { override fun isBackdropInvalidated(backdropView: View): Boolean { return isBackdropContentChanged(backdropView) } } ) ``` The `isBackdropInvalidated` method is called before a frame is drawn for each element with the effect, so it must be fast. ## Example {#example} {% cut "Panel with the effect on top of an image" %} ```json translate=no { "card": { "log_id": "backdrop_effect_sample", "states": [ { "state_id": 0, "div": { "type": "container", "orientation": "overlap", "items": [ { "type": "image", "id": "photo", "image_url": "https://example.com/image.png", "aspect": { "ratio": 1.5 } }, { "type": "text", "text": "Backdrop effect", "font_size": 16, "text_color": "#FFFFFFFF", "alignment_horizontal": "center", "alignment_vertical": "center", "width": { "type": "wrap_content" }, "paddings": { "left": 24, "right": 24, "top": 12, "bottom": 12 }, "border": { "corner_radius": 16 }, "background": [ { "type": "solid", "color": "#33FFFFFF" } ], "extensions": [ { "id": "backdrop_effect", "params": { "backdrop_id": "photo", "blur": { "radius": 8 }, "refraction": { "height": 12, "strength": 24 }, "rim_highlight": { "type": "ambient", "intensity": 0.4 } } } ] } ] } } ] } } ``` In this example, the image with the `photo` ID is the backdrop for the effect, and the corner rounding of the effect is set by the `border` property of the text element. {% endcut %} {% cut "Example with backdrop_scope: window" %} ```json translate=no { "extensions": [ { "id": "backdrop_effect", "params": { "blur": { "radius": 15 }, "backdrop_scope": "window" } } ] } ``` This example blurs the entire application window background beneath the element, including content outside the current card. {% endcut %} ## 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)