Cloudy

Kotlin Multiplatform surface effects library for Compose — blur, liquid glass, and shader-driven looks — with GPU-accelerated rendering and CPU fallback for older devices. See documentation for more details.

Cloudy started as a backport of the blur effect for Jetpack Compose with cross-platform support, and has grown to cover liquid glass and open shader effects as well. The `Modifier.cloudy(radius = …)` blur path supports only Android 12 and higher without the deprecated `RenderScript` APIs; see Platform Support for the CPU fallback on older devices.

Cloudy ships four independent effects you can mix and match on any composable — pick the ones you need:

Table of contents

• Download
• Part I — Effects
  • Self blur
  • Backdrop blur
  • Liquid Glass
  • Mirage
• Part II — Going further
  • Motion-driven light sources
  • Authoring your own Mirage optic
  • Blur effect with network images
• Acknowledgements
• License

Download

Version Catalog

If you're using Version Catalog, you can configure the dependency by adding it to your libs.versions.toml file as follows:

[versions]
#...
cloudy = "0.6.1"

[libraries]
#...
compose-cloudy = { module = "com.github.skydoves:cloudy", version.ref = "cloudy" }

Gradle

Add the dependency below to your module's build.gradle.kts file:

dependencies {
    implementation("com.github.skydoves:cloudy:0.6.1")

    // if you're using Version Catalog
    implementation(libs.compose.cloudy)
}

For Kotlin Multiplatform, add the dependency below to your module's build.gradle.kts file:

sourceSets {
    commonMain.dependencies {
        implementation("com.github.skydoves:cloudy:$version")
    }
}

Part I — Effects

Self blur

Cloudy offers two blur modes: Modifier.cloudy(radius = …) blurs a composable's own content (covered here), while Backdrop blur blurs the content behind a composable for glassmorphism surfaces.

Basic Usage

You can implement blur effect with Modifier.cloudy() composable function as seen below:

Text(
  modifier = Modifier.cloudy(),
  text = "This text is blurred"
)

You can change the degree of the blur effect by changing the radius parameter of Modifier.cloudy() composable function.

Column(
  modifier = Modifier.cloudy(radius = 15)
) {
  Image(..)

  Text(
    modifier = Modifier
      .fillMaxWidth()
      .padding(8.dp),
    text = posterModel.name,
    fontSize = 40.sp,
    color = MaterialTheme.colors.onBackground,
    textAlign = TextAlign.Center
  )

  Text(
    modifier = Modifier
      .fillMaxWidth()
      .padding(8.dp),
    text = posterModel.description,
    color = MaterialTheme.colors.onBackground,
    textAlign = TextAlign.Center
  )
}

Observing Blurring Status

You can monitor the status of the blurring effect by using the onStateChanged parameter, which provides CloudyState. This allows you to observe and respond to changes in the blurring effect's state effectively.

GlideImage(
  modifier = Modifier
    .size(400.dp)
    .cloudy(
      radius = 25,
      onStateChanged = { state ->
        when (state) {
          is CloudyState.Success.Applied -> {
            // GPU blur applied (iOS, Android 31+)
            // No bitmap available - blur rendered directly
          }
          is CloudyState.Success.Captured -> {
            // CPU blur completed (Android 30-)
            // Blurred bitmap available: state.bitmap
            val blurredBitmap = state.bitmap
          }
          is CloudyState.Loading -> {
            // Blur processing in progress
          }
          is CloudyState.Error -> {
            // Handle error: state.throwable
          }
          CloudyState.Nothing -> {
            // Initial state
          }
        }
      }
    ),
  ..
)

CloudyState has the following types:

Maintaining Blurring Effect on Responsive Composable

The Modifier.cloudy captures the bitmap of the composable node under the hood.

LazyVerticalGrid(
  state = rememberLazyGridState(),
  columns = GridCells.Fixed(2)
) {
  itemsIndexed(key = { index, item -> item.id }, items = posters) { index, item ->
    HomePoster(poster = item)
  }
}

@Composable
private fun HomePoster(poster: Poster) {
    ConstraintLayout {
      val (image, title, content) = createRefs()
      GlideImage(
        modifier = Modifier
          .cloudy(radius = 15)
          .aspectRatio(0.8f)
          .constrainAs(image) {
            centerHorizontallyTo(parent)
            top.linkTo(parent.top)
          }
          ..

Platform Support (Self Blur)

See Backdrop blur and Liquid Glass for their own platform support tables.

Backdrop blur

Background blur — also called backdrop blur — blurs the content that sits behind a composable, producing a glassmorphism / frosted-glass surface such as a translucent app bar, bottom navigation, or card. Unlike Modifier.cloudy(radius = …), which blurs a composable's own content, the backdrop API samples a shared snapshot of the background and renders it blurred underneath your overlay.

It is built from three pieces:

https://github.com/user-attachments/assets/c22cb656-4415-471e-a30a-521d39344447

https://github.com/user-attachments/assets/faf67c77-cb1e-4b20-994b-bb8afe340087

Basic Usage

Put Modifier.sky(sky) on the background you want to blur, then overlay a composable with Modifier.cloudy(sky = sky, …):

val sky = rememberSky()

Box(modifier = Modifier.fillMaxSize()) {
  // 1) Source — the content captured for blur
  LazyVerticalGrid(
    columns = GridCells.Fixed(2),
    modifier = Modifier.sky(sky),
  ) {
    items(posters) { poster -> GridPosterItem(poster) }
  }

  // 2) Overlay — a frosted glass app bar that blurs the grid behind it
  Box(
    modifier = Modifier
      .fillMaxWidth()
      .height(56.dp)
      .cloudy(
        sky = sky,
        radius = 20,
        tint = MaterialTheme.colorScheme.surface.copy(alpha = 0.3f),
      )
  ) {
    Text("Frosted Glass App Bar")
  }
}

Clipping to a Shape

By default the blurred backdrop is clipped to a rectangle. Pass a shape so the blur follows rounded corners instead of leaving a hard rectangular box inside a rounded glass surface:

val barShape = RoundedCornerShape(36.dp)

Row(
  modifier = Modifier
    .clip(barShape)
    .cloudy(sky = sky, radius = 24, shape = barShape)
    .background(Color.White.copy(alpha = 0.15f)),
) {
  // tabs
}

Progressive (Gradient) Blur

Use the progressive parameter to fade the blur across the surface — ideal for scroll-edge fades or vignettes:

// Blur is strongest at the top and fades to clear toward the bottom
Modifier.cloudy(
  sky = sky,
  radius = 25,
  progressive = CloudyProgressive.TopToBottom(),
)

Progressive blur uses an AGSL shader on Android 33+ and Skia shaders on iOS/macOS/Desktop/WASM. On Android 32 and below it falls back to uniform blur.

Refreshing the Blur

The backdrop refreshes automatically while the background scrolls or animates, and parks at zero frames once it settles. When the background changes outside of a scroll/animation (for example, an image finishes loading or you swap content), call Sky.invalidate() to re-capture:

AsyncImage(
  model = imageUrl,
  modifier = Modifier.sky(sky),
  onSuccess = { sky.invalidate() },
)

For an animated change that lasts a known duration (e.g. a tab cross-fade), pass the duration so the blur tracks the whole transition instead of freezing once the short settle tail elapses:

LaunchedEffect(selectedTab) {
  sky.invalidate(durationMillis = 240) // matches the cross-fade duration
}

Parameters (Modifier.cloudy(sky = …))

Platform Behavior (Background Blur)

On Android 30 and below, CPU blur is disabled by default and a semi-transparent scrim (CloudyState.Success.Scrim) is shown instead, following a performance-first approach. Set cpuBlurEnabled = true to force CPU blur on those devices.

Liquid Glass

Cloudy provides a Modifier.liquidGlass() that creates a realistic glass lens effect with SDF-based crisp edges, normal-based refraction, and chromatic dispersion.

Note: For blur effects, use Modifier.cloudy() separately. The two modifiers are designed to work independently, giving you full control over each effect.

Basic Usage

var lensCenter by remember { mutableStateOf(Offset(100f, 100f)) }

Box(
  modifier = Modifier
    .fillMaxSize()
    .pointerInput(Unit) {
      detectDragGestures { change, _ ->
        lensCenter = change.position
      }
    }
    .cloudy(radius = 15) // Use Cloudy for blur (independent)
    .liquidGlass(lensCenter = lensCenter) // Lens distortion effect
) {
  Image(
    painter = painterResource(R.drawable.photo),
    contentDescription = null,
    modifier = Modifier.fillMaxSize()
  )
}

Combining with Cloudy Blur

The liquidGlass() and cloudy() modifiers are independent and composable:

// Blur only
.cloudy(radius = 20)

// Lens effect only
.liquidGlass(lensCenter = lensCenter)

// Both effects combined
.cloudy(radius = 15)
.liquidGlass(lensCenter = lensCenter)

This separation gives you full access to Cloudy's blur API (radius, onStateChanged, CloudyState) while using the liquid glass lens effect.

Customization