# CompositionLocal

Artifact: [androidx.compose.runtime:runtime](https://developer.android.com/jetpack/androidx/releases/compose-runtime) [View Source](https://cs.android.com/search?q=file:androidx/compose/runtime/CompositionLocal.kt+class:androidx.compose.runtime.CompositionLocal) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/compose-runtime#1.0.0) Common/AllAndroid/JVMNative/C/iOSJavaScript
- Cmn

  ```
  sealed class CompositionLocal<T : Any?>
  ```
Known direct subclasses [ProvidableCompositionLocal](https://developer.android.com/reference/kotlin/androidx/compose/runtime/ProvidableCompositionLocal)

|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ProvidableCompositionLocal` | A `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ProvidableCompositionLocal` can be used in `https://developer.android.com/reference/kotlin/androidx/compose/runtime/CompositionLocalProvider.composable#CompositionLocalProvider(kotlin.Array,kotlin.Function0)` to provide values. |

*** ** * ** ***

Compose passes data through the composition tree explicitly through means of parameters to composable functions. This is often times the simplest and best way to have data flow through the tree.

Sometimes this model can be cumbersome or break down for data that is needed by lots of components, or when components need to pass data between one another but keep that implementation detail private. For these cases, `https://developer.android.com/reference/kotlin/androidx/compose/runtime/CompositionLocal`s can be used as an implicit way to have data flow through a composition.

`https://developer.android.com/reference/kotlin/androidx/compose/runtime/CompositionLocal`s by their nature are hierarchical. They make sense when the value of the `https://developer.android.com/reference/kotlin/androidx/compose/runtime/CompositionLocal` needs to be scoped to a particular sub-hierarchy of the composition.

One must create a `https://developer.android.com/reference/kotlin/androidx/compose/runtime/CompositionLocal` instance, which can be referenced by the consumers statically. `https://developer.android.com/reference/kotlin/androidx/compose/runtime/CompositionLocal` instances themselves hold no data, and can be thought of as a type-safe identifier for the data being passed down a tree. `https://developer.android.com/reference/kotlin/androidx/compose/runtime/CompositionLocal` factory functions take a single parameter: a factory to create a default value in cases where a `https://developer.android.com/reference/kotlin/androidx/compose/runtime/CompositionLocal` is used without a Provider. If this is a situation you would rather not handle, you can throw an error in this factory.

```kotlin
import androidx.compose.runtime.compositionLocalOf

val ActiveUser = compositionLocalOf<User> { error("No active user found!") }
```

Somewhere up the tree, a `https://developer.android.com/reference/kotlin/androidx/compose/runtime/CompositionLocalProvider.composable#CompositionLocalProvider(kotlin.Array,kotlin.Function0)` component can be used, which provides a value for the `https://developer.android.com/reference/kotlin/androidx/compose/runtime/CompositionLocal`. This would often be at the "root" of a tree, but could be anywhere, and can also be used in multiple places to override the provided value for a sub-tree.

```kotlin
import androidx.compose.runtime.Composable
import androidx.compose.runtime.CompositionLocalProvider

@Composable
fun App(user: User) {
    CompositionLocalProvider(ActiveUser provides user) { SomeScreen() }
}
```

Intermediate components do not need to know about the `https://developer.android.com/reference/kotlin/androidx/compose/runtime/CompositionLocal` value, and can have zero dependencies on it. For example, `SomeScreen` might look like this:

```kotlin
import androidx.compose.runtime.Composable

@Composable
fun SomeScreen() {
    UserPhoto()
}
```

Finally, a component that wishes to consume the `https://developer.android.com/reference/kotlin/androidx/compose/runtime/CompositionLocal` value can use the `https://developer.android.com/reference/kotlin/androidx/compose/runtime/CompositionLocal#current()` property of the `https://developer.android.com/reference/kotlin/androidx/compose/runtime/CompositionLocal` key which returns the current value of the `https://developer.android.com/reference/kotlin/androidx/compose/runtime/CompositionLocal`, and subscribes the component to changes of it.

```kotlin
import androidx.compose.runtime.Composable

@Composable
fun UserPhoto() {
    val user = ActiveUser.current
    ProfileIcon(src = user.profilePhotoUrl)
}
```

## Summary

| ### Protected constructors |
|---|---|
| `<T : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?> https://developer.android.com/reference/kotlin/androidx/compose/runtime/CompositionLocal#CompositionLocal(kotlin.Function0)(defaultFactory: () -> T)` | Cmn |

| ### Public properties |
|---|---|---|
| `T` | `https://developer.android.com/reference/kotlin/androidx/compose/runtime/CompositionLocal#current()` Return the value provided by the nearest `https://developer.android.com/reference/kotlin/androidx/compose/runtime/CompositionLocalProvider.composable#CompositionLocalProvider(kotlin.Array,kotlin.Function0)` component that invokes, directly or indirectly, the composable function that uses this property. | Cmn |

## Protected constructors

### CompositionLocal

Cmn

```
protected <T : Any?> CompositionLocal(defaultFactory: () -> T)
```

## Public properties

### current

Cmn Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/compose-runtime#1.0.0)

```
val current: T
```

Return the value provided by the nearest `https://developer.android.com/reference/kotlin/androidx/compose/runtime/CompositionLocalProvider.composable#CompositionLocalProvider(kotlin.Array,kotlin.Function0)` component that invokes, directly or indirectly, the composable function that uses this property.

```kotlin
import androidx.compose.runtime.Composable

@Composable
fun UserPhoto() {
    val user = ActiveUser.current
    ProfileIcon(src = user.profilePhotoUrl)
}
```