derivedMediaQuery

Functions summary

State<T>

@ExperimentalMediaQueryApi
@Composable
<T : Any?> derivedMediaQuery(query: UiMediaScope.() -> T)

Evaluates a query against the current UiMediaScope, wrapped in a derivedStateOf.

Cmn

Functions

derivedMediaQuery

Cmn

Artifact: androidx.compose.ui:ui

View Source

@ExperimentalMediaQueryApi
@Composable
fun <T : Any?> derivedMediaQuery(query: UiMediaScope.() -> T): State<T>

Evaluates a query against the current UiMediaScope, wrapped in a derivedStateOf.

Use this function for queries that involve frequently changing values, such as UiMediaScope.windowWidth or UiMediaScope.windowHeight. It ensures that compositions only recompose when the result of the query changes, not on every small change to the underlying values (like a 1px size change).

For queries on stable properties, you can use the simpler mediaQuery function.

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.fillMaxHeight
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.width
import androidx.compose.ui.Modifier
import androidx.compose.ui.UiMediaScope.ViewingDistance
import androidx.compose.ui.derivedMediaQuery
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

Box(Modifier.fillMaxSize().padding(top = 100.dp)) {
    val showDualPane by derivedMediaQuery { windowWidth >= 600.dp }
    val showNavigationRail by derivedMediaQuery {
        windowWidth >= 500.dp && viewingDistance != ViewingDistance.Near
    }

    Column(Modifier.fillMaxSize()) {
        Row(Modifier.weight(1f).fillMaxWidth()) {
            if (showNavigationRail) {
                // Show navigation rail
                Box(Modifier.width(150.dp).background(Color.Red).fillMaxHeight())
            }

            // Actual content
            Box(Modifier.weight(1f).background(Color.Yellow).fillMaxHeight())

            if (showDualPane) {
                // Split screen into 2 panes for additional content
                Box(Modifier.weight(1f).background(Color.Cyan).fillMaxHeight())
            }
        }

        if (!showNavigationRail && !showDualPane) {
            // Show bottom navigation
            Box(Modifier.background(Color.Blue).height(80.dp).fillMaxWidth())
        }
    }
}

Parameters
`query: UiMediaScope.() -> T`	The condition to evaluate against the `UiMediaScope`.

Returns
`State<T>`	A `State` holding the result of the query. The state will only update when the evaluated result of the query changes.