haze-patterns

name	haze-patterns
description	Expert guidance on common Haze usage patterns and recipes. Use when implementing Scaffold blur, sticky headers, overlapping effects, dialog blur, or deep hierarchy state sharing with Haze.

Haze Patterns — Common Recipes

Instructions

1. Scaffold with Blurred App Bars

Multiple hazeEffect modifiers share one HazeState:

val hazeState = rememberHazeState()

Scaffold(
    topBar = {
        TopAppBar(
            colors = TopAppBarDefaults.largeTopAppBarColors(Color.Transparent),
            modifier = Modifier.hazeEffect(hazeState) {
                blurEffect { style = HazeMaterials.thin() }
            }
        )
    },
    bottomBar = {
        NavigationBar(
            containerColor = Color.Transparent,
            modifier = Modifier.hazeEffect(hazeState) {
                blurEffect { style = HazeMaterials.thin() }
            }
        )
    }
) { padding ->
    LazyColumn(
        modifier = Modifier.padding(padding).hazeSource(hazeState)
    ) { /* content */ }
}

[!KEY] App bars must have transparent background colors to see the blur effect.

2. Dialog Blur

Blur dialog backgrounds over underlying content:

val hazeState = rememberHazeState()
var showDialog by remember { mutableStateOf(false) }

Box {
    // Mark background as blur source FIRST
    LazyVerticalGrid(
        modifier = Modifier.hazeSource(state = hazeState)
    ) { /* content */ }

    if (showDialog) {
        Dialog(onDismissRequest = { showDialog = false }) {
            Surface(
                modifier = Modifier.fillMaxWidth().fillMaxHeight(0.5f),
                shape = MaterialTheme.shapes.extraLarge,
                color = MaterialTheme.colorScheme.surface.copy(alpha = 0.2f),
            ) {
                Box(Modifier.hazeEffect(state = hazeState) {
                    blurEffect { style = HazeMaterials.regular() }
                }) {
                    // dialog content
                }
            }
        }
    }
}

[!IMPORTANT] With dialogs, colorEffects tints display as a scrim. Use a translucent color on the dialog Surface instead.

3. Sticky Headers

Apply hazeSource on all non-header items, hazeEffect on the sticky header:

val hazeState = rememberHazeState()

LazyColumn {
    stickyHeader {
        Header(
            modifier = Modifier.hazeEffect(hazeState) {
                blurEffect { style = HazeMaterials.thin() }
            }
        )
    }
    items(list) { item ->
        Foo(modifier = Modifier.hazeSource(hazeState))
    }
}

Avoid recursive drawing: don't put hazeSource on the LazyColumn and hazeEffect on items within it.

4. Overlapping Blurred Cards

A composable can be both source and effect target simultaneously using zIndex:

Box {
    val hazeState = rememberHazeState()

    // Background at zIndex 0
    AsyncImage(
        modifier = Modifier.fillMaxSize().hazeSource(hazeState, zIndex = 0f),
        model = "...", contentDescription = null
    )

    // Rear card — draws background blur, serves as source for cards above
    CreditCard(
        modifier = Modifier
            .hazeSource(hazeState, zIndex = 1f)
            .hazeEffect(hazeState) { blurEffect { style = HazeMaterials.thin() } }
    )

    // Middle card
    CreditCard(
        modifier = Modifier
            .hazeSource(hazeState, zIndex = 2f)
            .hazeEffect(hazeState) { blurEffect { style = HazeMaterials.thin() } }
    )

    // Front card
    CreditCard(
        modifier = Modifier
            .hazeSource(hazeState, zIndex = 3f)
            .hazeEffect(hazeState) { blurEffect { style = HazeMaterials.thin() } }
    )
}

[!NOTE] By default, a hazeEffect draws all layers with zIndex less than its sibling hazeSource.

5. Filtering Source Areas

Exclude specific layers from an effect via canDrawArea:

CreditCard(
    modifier = Modifier
        .hazeSource(hazeState, zIndex = 2f, key = "self")
        .hazeEffect(hazeState) {
            canDrawArea = { area -> area.key != "self" }  // Exclude self
            blurEffect { /* ... */ }
        }
)

6. Deep Hierarchy — Composition Local

Avoid prop drilling through nested composables:

val LocalHazeState = compositionLocalOf { HazeState() }

@Composable
fun Screen() {
    val hazeState = rememberHazeState()
    CompositionLocalProvider(LocalHazeState provides hazeState) {
        Box {
            ContentLayer()   // internally uses LocalHazeState.current for hazeSource
            OverlayLayer()   // internally uses LocalHazeState.current for hazeEffect
        }
    }
}

@Composable
fun OverlayLayer() {
    TopAppBar(
        modifier = Modifier.hazeEffect(state = LocalHazeState.current) {
            blurEffect { style = HazeMaterials.thin() }
        }
    )
}

7. Integrated Source and Effect on Same Node

A layout can use both hazeSource and hazeEffect on itself:

Card(
    modifier = Modifier
        .hazeSource(hazeState, zIndex = 1f)
        .hazeEffect(hazeState) {
            blurEffect { style = HazeMaterials.thin() }
        }
) {
    // Card content that blurs background AND serves as blur source for overlays above
}

8. Position Strategy for Split-Window

Fix blur misalignment in split-window modes (e.g., Huawei Parallel Space):

// Keep same-window coordinates (immune to split-window offset issues)
val hazeState = rememberHazeState(positionStrategy = HazePositionStrategy.Local)

9. Checklist

• Transparent overlay backgrounds to reveal the blur.
• Dialogs: translucent surface color instead of colorEffects.
• Sticky headers: hazeSource on items, not on the LazyColumn.
• zIndex ordering for overlapping effects (lower = further back).
• CompositionLocal for deep hierarchies.