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

{
  "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

All parameters are optional. The extension parameters don't support expressions.

The corner rounding of the effect is taken from the border property of the element: corner_radius or corners_radius.

Backdrop search area

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.

Blur

Refraction

Color adjustment

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.

How it works

• 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

build.gradle

dependencies {
    implementation "com.yandex.div:backdrop-effect:${versions.divkit}"
}

In the code:

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:

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

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

{
  "extensions": [
    {
      "id": "backdrop_effect",
      "params": {
        "blur": {
          "radius": 15
        },
        "backdrop_scope": "window"
      }
    }
  ]
}

Learn more

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

DivKit Repository