Skip to content
🤔 Documentation issue? Report or edit

CompositionLocal

Info

This is the API of version 1.0.0-beta02

CompositionLocal is useful when you want to create a dependency in a higher node of the layout tree and use it on lower node without having to pass it down the tree through every child Composable.

How to create an CompositionLocal?

data class User(val name: String, val age: Int)
val LocalActiveUser = compositionLocalOf<User> { error("No user found!") }
Let’s say you want to create an CompositionLocal with an User. You can use compositionLocalOf. Inside the function you can return an initial user object or you can throw an exception when the user is missing.

How to provide a value for an CompositionLocal?

@Composable
private fun MyUserScreen() {
    val user = User("Jens", 31)
    CompositionLocalProvider(LocalActiveUser provides user) {
        UserInfo()
    }
}
Somewhere above in your hierarchy you have to use CompositionLocalProvider to provide a value for your CompositionLocal. The syntax is: “CompositionLocal<T> provides T”. All child @Composable of CompositionLocalProvider will implicitly be able to get the value of the CompositionLocals.

How to use a value of an CompositionLocal?

@Preview
@Composable
fun UserInfo() {
    Column {
        Text("Name: " + LocalActiveUser.current.name)
        Text("Age: " + LocalActiveUser.current.age)
    }
}

Now you can use your CompositionLocal in your @Composable. Every CompositionLocal has a current property that contains the current value.

Predefined CompositionLocals

The Compose libraries already contain some useful CompositionLocals. You can directly use them without needing add a Providers.

LocalContext

Provides a [Context] that can be used by Android applications.

LocalConfiguration

The [Configuration] is useful for determining how to organize the UI.

Device orientation

One of the things you can get from the LocalConfiguration is the orientation of your device. This can be used to give the user a different ui when the device is rotated.

val configuration = LocalConfiguration.current
when (configuration.orientation) {
    Configuration.ORIENTATION_LANDSCAPE -> {
        Text("Landscape")
    }
    else -> {
        Text("Portrait")
    }
}

LocalLifecycleOwner

The CompositionLocal containing the current [LifecycleOwner].

LocalView

The CompositionLocal containing the current Compose [View].

LocalViewModelStoreOwner

The CompositionLocal containing the current [ViewModelStoreOwner].

See also:


Last update: March 11, 2021