{% setvar book_path %}/reference/androidx/_book.yaml{% endsetvar %} {% include "_shared/_reference-head-tags.html" %}

CompositionLocalKt

public final class CompositionLocalKt


Summary

Public methods

static final void

CompositionLocalProvider binds values to CompositionLocal's, provided by context.

static final void
@Composable
CompositionLocalProvider(
    @NonNull ProvidedValue<@NonNull ?> values,
    @Composable @NonNull Function0<Unit> content
)

CompositionLocalProvider binds values to ProvidableCompositionLocal keys.

static final @NonNull ProvidableCompositionLocal<@NonNull T>
<T extends Object> compositionLocalOf(
    @NonNull SnapshotMutationPolicy<@NonNull T> policy,
    @NonNull Function0<@NonNull T> defaultFactory
)

Create a CompositionLocal key that can be provided using CompositionLocalProvider.

static final @NonNull ProvidableCompositionLocal<@NonNull T>
<T extends Object> staticCompositionLocalOf(
    @NonNull Function0<@NonNull T> defaultFactory
)

Create a CompositionLocal key that can be provided using CompositionLocalProvider.

Public methods

CompositionLocalProvider

@Composable
public static final void CompositionLocalProvider(
    @NonNull CompositionLocalContext context,
    @Composable @NonNull Function0<Unit> content
)

CompositionLocalProvider binds values to CompositionLocal's, provided by context. Reading the CompositionLocal using CompositionLocal.current will return the value provided in values stored inside context for all composable functions called directly or indirectly in the content lambda.

import androidx.compose.runtime.Composable
import androidx.compose.runtime.CompositionLocalProvider

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

CompositionLocalProvider

@Composable
public static final void CompositionLocalProvider(
    @NonNull ProvidedValue<@NonNull ?> values,
    @Composable @NonNull Function0<Unit> content
)

CompositionLocalProvider binds values to ProvidableCompositionLocal keys. Reading the CompositionLocal using CompositionLocal.current will return the value provided in CompositionLocalProvider's values parameter for all composable functions called directly or indirectly in the content lambda.

import androidx.compose.runtime.Composable
import androidx.compose.runtime.CompositionLocalProvider

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

compositionLocalOf

public static final @NonNull ProvidableCompositionLocal<@NonNull T> <T extends Object> compositionLocalOf(
    @NonNull SnapshotMutationPolicy<@NonNull T> policy,
    @NonNull Function0<@NonNull T> defaultFactory
)

Create a CompositionLocal key that can be provided using CompositionLocalProvider. Changing the value provided during recomposition will invalidate the content of CompositionLocalProvider that read the value using CompositionLocal.current.

compositionLocalOf creates a ProvidableCompositionLocal which can be used in a a call to CompositionLocalProvider. Similar to MutableList vs. List, if the key is made public as CompositionLocal instead of ProvidableCompositionLocal, it can be read using CompositionLocal.current but not re-provided.

Parameters
@NonNull SnapshotMutationPolicy<@NonNull T> policy

a policy to determine when a CompositionLocal is considered changed. See SnapshotMutationPolicy for details.

@NonNull Function0<@NonNull T> defaultFactory

a value factory to supply a value when a value is not provided. This factory is called when no value is provided through a CompositionLocalProvider of the caller of the component using CompositionLocal.current. If no reasonable default can be provided then consider throwing an exception.

staticCompositionLocalOf

public static final @NonNull ProvidableCompositionLocal<@NonNull T> <T extends Object> staticCompositionLocalOf(
    @NonNull Function0<@NonNull T> defaultFactory
)

Create a CompositionLocal key that can be provided using CompositionLocalProvider.

Unlike compositionLocalOf, reads of a staticCompositionLocalOf are not tracked by the composer and changing the value provided in the CompositionLocalProvider call will cause the entirety of the content to be recomposed instead of just the places where in the composition the local value is used. This lack of tracking, however, makes a staticCompositionLocalOf more efficient when the value provided is highly unlikely to or will never change. For example, the android context, font loaders, or similar shared values, are unlikely to change for the components in the content of a the CompositionLocalProvider and should consider using a staticCompositionLocalOf. A color, or other theme like value, might change or even be animated therefore a compositionLocalOf should be used.

staticCompositionLocalOf creates a ProvidableCompositionLocal which can be used in a a call to CompositionLocalProvider. Similar to MutableList vs. List, if the key is made public as CompositionLocal instead of ProvidableCompositionLocal, it can be read using CompositionLocal.current but not re-provided.

Parameters
@NonNull Function0<@NonNull T> defaultFactory

a value factory to supply a value when a value is not provided. This factory is called when no value is provided through a CompositionLocalProvider of the caller of the component using CompositionLocal.current. If no reasonable default can be provided then consider throwing an exception.