androidx.compose.runtime

@Composable
inline fun <T : Any, E : Applier<*>> ComposeNode(
    noinline factory: () -> T,
    update: @DisallowComposableCalls Updater<T>.() -> Unit
): Unit

Emits a node into the composition of type T.

This function will throw a runtime exception if E is not a subtype of the applier of the currentComposer.

import androidx.compose.runtime.AbstractApplier
import androidx.compose.runtime.Composable
import androidx.compose.runtime.ComposeNode
import androidx.compose.runtime.Composition
import androidx.compose.runtime.CompositionContext
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

// Provided we have a tree with a node base type like the following
abstract class Node {
    val children = mutableListOf<Node>()
}

// We would implement an Applier class like the following, which would teach compose how to
// manage a tree of Nodes.
class NodeApplier(root: Node) : AbstractApplier<Node>(root) {
    override fun insertTopDown(index: Int, instance: Node) {
        current.children.add(index, instance)
    }

    override fun insertBottomUp(index: Int, instance: Node) {
        // Ignored as the tree is built top-down.
    }

    override fun remove(index: Int, count: Int) {
        current.children.remove(index, count)
    }

    override fun move(from: Int, to: Int, count: Int) {
        current.children.move(from, to, count)
    }

    override fun onClear() {
        root.children.clear()
    }
}

// A function like the following could be created to create a composition provided a root Node.
fun Node.setContent(parent: CompositionContext, content: @Composable () -> Unit): Composition {
    return Composition(NodeApplier(this), parent).apply { setContent(content) }
}

// assuming we have Node sub-classes like "TextNode" and "GroupNode"
class TextNode : Node() {
    var text: String = ""
    var onClick: () -> Unit = {}
}
class GroupNode : Node()

// Composable equivalents could be created
@Composable
fun Text(text: String, onClick: () -> Unit = {}) {
    ComposeNode<TextNode, NodeApplier>(::TextNode) {
        set(text) { this.text = it }
        set(onClick) { this.onClick = it }
    }
}

@Composable
fun Group(content: @Composable () -> Unit) {
    ComposeNode<GroupNode, NodeApplier>(::GroupNode, {}, content)
}

// and then a sample tree could be composed:
fun runApp(root: GroupNode, parent: CompositionContext) {
    root.setContent(parent) {
        var count by remember { mutableStateOf(0) }
        Group {
            Text("Count: $count")
            Text("Increment") { count++ }
        }
    }
}

@Composable
inline fun <T : Any?, E : Applier<*>> ComposeNode(
    noinline factory: () -> T,
    update: @DisallowComposableCalls Updater<T>.() -> Unit,
    content: @Composable () -> Unit
): Unit

Emits a node into the composition of type T. Nodes emitted inside of content will become children of the emitted node.

This function will throw a runtime exception if E is not a subtype of the applier of the currentComposer.

import androidx.compose.runtime.AbstractApplier
import androidx.compose.runtime.Composable
import androidx.compose.runtime.ComposeNode
import androidx.compose.runtime.Composition
import androidx.compose.runtime.CompositionContext
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

// Provided we have a tree with a node base type like the following
abstract class Node {
    val children = mutableListOf<Node>()
}

// We would implement an Applier class like the following, which would teach compose how to
// manage a tree of Nodes.
class NodeApplier(root: Node) : AbstractApplier<Node>(root) {
    override fun insertTopDown(index: Int, instance: Node) {
        current.children.add(index, instance)
    }

    override fun insertBottomUp(index: Int, instance: Node) {
        // Ignored as the tree is built top-down.
    }

    override fun remove(index: Int, count: Int) {
        current.children.remove(index, count)
    }

    override fun move(from: Int, to: Int, count: Int) {
        current.children.move(from, to, count)
    }

    override fun onClear() {
        root.children.clear()
    }
}

// A function like the following could be created to create a composition provided a root Node.
fun Node.setContent(parent: CompositionContext, content: @Composable () -> Unit): Composition {
    return Composition(NodeApplier(this), parent).apply { setContent(content) }
}

// assuming we have Node sub-classes like "TextNode" and "GroupNode"
class TextNode : Node() {
    var text: String = ""
    var onClick: () -> Unit = {}
}
class GroupNode : Node()

// Composable equivalents could be created
@Composable
fun Text(text: String, onClick: () -> Unit = {}) {
    ComposeNode<TextNode, NodeApplier>(::TextNode) {
        set(text) { this.text = it }
        set(onClick) { this.onClick = it }
    }
}

@Composable
fun Group(content: @Composable () -> Unit) {
    ComposeNode<GroupNode, NodeApplier>(::GroupNode, {}, content)
}

// and then a sample tree could be composed:
fun runApp(root: GroupNode, parent: CompositionContext) {
    root.setContent(parent) {
        var count by remember { mutableStateOf(0) }
        Group {
            Text("Count: $count")
            Text("Increment") { count++ }
        }
    }
}

@Composable
@ExplicitGroupsComposable
inline fun <T : Any?, E : Applier<*>> ComposeNode(
    noinline factory: () -> T,
    update: @DisallowComposableCalls Updater<T>.() -> Unit,
    noinline skippableUpdate: @Composable SkippableUpdater<T>.() -> Unit,
    content: @Composable () -> Unit
): Unit

Emits a node into the composition of type T. Nodes emitted inside of content will become children of the emitted node.

This function will throw a runtime exception if E is not a subtype of the applier of the currentComposer.

import androidx.compose.runtime.AbstractApplier
import androidx.compose.runtime.Composable
import androidx.compose.runtime.ComposeNode
import androidx.compose.runtime.Composition
import androidx.compose.runtime.CompositionContext
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

// Provided we have a tree with a node base type like the following
abstract class Node {
    val children = mutableListOf<Node>()
}

// We would implement an Applier class like the following, which would teach compose how to
// manage a tree of Nodes.
class NodeApplier(root: Node) : AbstractApplier<Node>(root) {
    override fun insertTopDown(index: Int, instance: Node) {
        current.children.add(index, instance)
    }

    override fun insertBottomUp(index: Int, instance: Node) {
        // Ignored as the tree is built top-down.
    }

    override fun remove(index: Int, count: Int) {
        current.children.remove(index, count)
    }

    override fun move(from: Int, to: Int, count: Int) {
        current.children.move(from, to, count)
    }

    override fun onClear() {
        root.children.clear()
    }
}

// A function like the following could be created to create a composition provided a root Node.
fun Node.setContent(parent: CompositionContext, content: @Composable () -> Unit): Composition {
    return Composition(NodeApplier(this), parent).apply { setContent(content) }
}

// assuming we have Node sub-classes like "TextNode" and "GroupNode"
class TextNode : Node() {
    var text: String = ""
    var onClick: () -> Unit = {}
}
class GroupNode : Node()

// Composable equivalents could be created
@Composable
fun Text(text: String, onClick: () -> Unit = {}) {
    ComposeNode<TextNode, NodeApplier>(::TextNode) {
        set(text) { this.text = it }
        set(onClick) { this.onClick = it }
    }
}

@Composable
fun Group(content: @Composable () -> Unit) {
    ComposeNode<GroupNode, NodeApplier>(::GroupNode, {}, content)
}

// and then a sample tree could be composed:
fun runApp(root: GroupNode, parent: CompositionContext) {
    root.setContent(parent) {
        var count by remember { mutableStateOf(0) }
        Group {
            Text("Count: $count")
            Text("Increment") { count++ }
        }
    }
}

fun Composition(applier: Applier<*>, parent: CompositionContext): Composition

This method is the way to initiate a composition. parent can be

• provided to make the composition behave as a sub-composition of the parent. If composition does

• not have a parent, Recomposer instance should be provided.

It is important to call Composition.dispose when composition is no longer needed in order to release resources.

import androidx.compose.runtime.AbstractApplier
import androidx.compose.runtime.Composable
import androidx.compose.runtime.ComposeNode
import androidx.compose.runtime.Composition
import androidx.compose.runtime.CompositionContext
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

// Provided we have a tree with a node base type like the following
abstract class Node {
    val children = mutableListOf<Node>()
}

// We would implement an Applier class like the following, which would teach compose how to
// manage a tree of Nodes.
class NodeApplier(root: Node) : AbstractApplier<Node>(root) {
    override fun insertTopDown(index: Int, instance: Node) {
        current.children.add(index, instance)
    }

    override fun insertBottomUp(index: Int, instance: Node) {
        // Ignored as the tree is built top-down.
    }

    override fun remove(index: Int, count: Int) {
        current.children.remove(index, count)
    }

    override fun move(from: Int, to: Int, count: Int) {
        current.children.move(from, to, count)
    }

    override fun onClear() {
        root.children.clear()
    }
}

// A function like the following could be created to create a composition provided a root Node.
fun Node.setContent(parent: CompositionContext, content: @Composable () -> Unit): Composition {
    return Composition(NodeApplier(this), parent).apply { setContent(content) }
}

// assuming we have Node sub-classes like "TextNode" and "GroupNode"
class TextNode : Node() {
    var text: String = ""
    var onClick: () -> Unit = {}
}
class GroupNode : Node()

// Composable equivalents could be created
@Composable
fun Text(text: String, onClick: () -> Unit = {}) {
    ComposeNode<TextNode, NodeApplier>(::TextNode) {
        set(text) { this.text = it }
        set(onClick) { this.onClick = it }
    }
}

@Composable
fun Group(content: @Composable () -> Unit) {
    ComposeNode<GroupNode, NodeApplier>(::GroupNode, {}, content)
}

// and then a sample tree could be composed:
fun runApp(root: GroupNode, parent: CompositionContext) {
    root.setContent(parent) {
        var count by remember { mutableStateOf(0) }
        Group {
            Text("Count: $count")
            Text("Increment") { count++ }
        }
    }
}

@ExperimentalComposeApi
fun Composition(
    applier: Applier<*>,
    parent: CompositionContext,
    recomposeCoroutineContext: CoroutineContext
): Composition

Create a Composition using applier to manage the composition, as a child of parent.

When used in a configuration that supports concurrent recomposition, hint to the environment that recomposeCoroutineContext should be used to perform recomposition. Recompositions will be launched into the

@Composable
fun CompositionLocalProvider(
    context: CompositionLocalContext,
    content: @Composable () -> Unit
): Unit

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() }
}

@Composable
@NonSkippableComposable
fun CompositionLocalProvider(
    value: ProvidedValue<*>,
    content: @Composable () -> Unit
): Unit

CompositionLocalProvider binds value to ProvidableCompositionLocal key. Reading the CompositionLocal using CompositionLocal.current will return the value provided in CompositionLocalProvider's value 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() }
}

@Composable
@NonSkippableComposable
fun CompositionLocalProvider(
    vararg values: ProvidedValue<*>,
    content: @Composable () -> Unit
): Unit

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() }
}

@TestOnly
fun ControlledComposition(applier: Applier<*>, parent: CompositionContext): ControlledComposition

This method is a way to initiate a composition. Optionally, a parent can be provided to make the composition behave as a sub-composition of the parent or a Recomposer can be provided.

A controlled composition allows direct control of the composition instead of it being controlled by the Recomposer passed ot the root composition.

It is important to call Composition.dispose this composer is no longer needed in order to release resources.

import androidx.compose.runtime.AbstractApplier
import androidx.compose.runtime.Composable
import androidx.compose.runtime.ComposeNode
import androidx.compose.runtime.Composition
import androidx.compose.runtime.CompositionContext
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

// Provided we have a tree with a node base type like the following
abstract class Node {
    val children = mutableListOf<Node>()
}

// We would implement an Applier class like the following, which would teach compose how to
// manage a tree of Nodes.
class NodeApplier(root: Node) : AbstractApplier<Node>(root) {
    override fun insertTopDown(index: Int, instance: Node) {
        current.children.add(index, instance)
    }

    override fun insertBottomUp(index: Int, instance: Node) {
        // Ignored as the tree is built top-down.
    }

    override fun remove(index: Int, count: Int) {
        current.children.remove(index, count)
    }

    override fun move(from: Int, to: Int, count: Int) {
        current.children.move(from, to, count)
    }

    override fun onClear() {
        root.children.clear()
    }
}

// A function like the following could be created to create a composition provided a root Node.
fun Node.setContent(parent: CompositionContext, content: @Composable () -> Unit): Composition {
    return Composition(NodeApplier(this), parent).apply { setContent(content) }
}

// assuming we have Node sub-classes like "TextNode" and "GroupNode"
class TextNode : Node() {
    var text: String = ""
    var onClick: () -> Unit = {}
}
class GroupNode : Node()

// Composable equivalents could be created
@Composable
fun Text(text: String, onClick: () -> Unit = {}) {
    ComposeNode<TextNode, NodeApplier>(::TextNode) {
        set(text) { this.text = it }
        set(onClick) { this.onClick = it }
    }
}

@Composable
fun Group(content: @Composable () -> Unit) {
    ComposeNode<GroupNode, NodeApplier>(::GroupNode, {}, content)
}

// and then a sample tree could be composed:
fun runApp(root: GroupNode, parent: CompositionContext) {
    root.setContent(parent) {
        var count by remember { mutableStateOf(0) }
        Group {
            Text("Count: $count")
            Text("Increment") { count++ }
        }
    }
}

@TestOnly
@ExperimentalComposeApi
fun ControlledComposition(
    applier: Applier<*>,
    parent: CompositionContext,
    recomposeCoroutineContext: CoroutineContext
): ControlledComposition

@Composable
@NonRestartableComposable
fun DisposableEffect(effect: DisposableEffectScope.() -> DisposableEffectResult): Unit

A side effect of composition that must be reversed or cleaned up if the DisposableEffect leaves the composition.

It is an error to call DisposableEffect without at least one key parameter.

@Composable
@NonRestartableComposable
fun DisposableEffect(key1: Any?, effect: DisposableEffectScope.() -> DisposableEffectResult): Unit

A side effect of composition that must run for any new unique value of key1 and must be reversed or cleaned up if key1 changes or if the DisposableEffect leaves the composition.

A DisposableEffect's key is a value that defines the identity of the DisposableEffect. If a key changes, the DisposableEffect must dispose its current effect and reset by calling effect again. Examples of keys include:

• Observable objects that the effect subscribes to

• Unique request parameters to an operation that must cancel and retry if those parameters change

DisposableEffect may be used to initialize or subscribe to a key and reinitialize when a different key is provided, performing cleanup for the old operation before initializing the new. For example:

import androidx.compose.runtime.Composable
import androidx.compose.runtime.DisposableEffect
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

@Composable
fun UserProfile(userRepository: UserRepository, userRequest: UserDataRequest) {
    var userDataState by remember { mutableStateOf<UserDataState>(UserDataState.Loading) }

    // If either the repository or request change, we must cancel our old data fetch
    // and begin a new data fetch. We will cancel the current data fetch if UserProfile
    // leaves the composition.
    DisposableEffect(userRepository, userRequest) {
        val requestDisposable =
            userRepository.fetchUserData(
                userRequest,
                onSuccess = { response -> userDataState = UserDataState.UserData(response) },
                onError = { throwable ->
                    userDataState = UserDataState.Error(throwable.message)
                }
            )

        onDispose { requestDisposable.dispose() }
    }

    // ...
}

A DisposableEffect must include an onDispose clause as the final statement in its effect block. If your operation does not require disposal it might be a SideEffect instead, or a LaunchedEffect if it launches a coroutine that should be managed by the composition.

There is guaranteed to be one call to dispose for every call to effect. Both effect and dispose will always be run on the composition's apply dispatcher and appliers are never run concurrent with themselves, one another, applying changes to the composition tree, or running RememberObserver event callbacks.

@Composable
@NonRestartableComposable
fun DisposableEffect(vararg keys: Any?, effect: DisposableEffectScope.() -> DisposableEffectResult): Unit

A side effect of composition that must run for any new unique value of keys and must be reversed or cleaned up if any keys change or if the DisposableEffect leaves the composition.

A DisposableEffect's key is a value that defines the identity of the DisposableEffect. If a key changes, the DisposableEffect must dispose its current effect and reset by calling effect again. Examples of keys include:

• Observable objects that the effect subscribes to

• Unique request parameters to an operation that must cancel and retry if those parameters change

DisposableEffect may be used to initialize or subscribe to a key and reinitialize when a different key is provided, performing cleanup for the old operation before initializing the new. For example:

import androidx.compose.runtime.Composable
import androidx.compose.runtime.DisposableEffect
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

@Composable
fun UserProfile(userRepository: UserRepository, userRequest: UserDataRequest) {
    var userDataState by remember { mutableStateOf<UserDataState>(UserDataState.Loading) }

    // If either the repository or request change, we must cancel our old data fetch
    // and begin a new data fetch. We will cancel the current data fetch if UserProfile
    // leaves the composition.
    DisposableEffect(userRepository, userRequest) {
        val requestDisposable =
            userRepository.fetchUserData(
                userRequest,
                onSuccess = { response -> userDataState = UserDataState.UserData(response) },
                onError = { throwable ->
                    userDataState = UserDataState.Error(throwable.message)
                }
            )

        onDispose { requestDisposable.dispose() }
    }

    // ...
}

A DisposableEffect must include an onDispose clause as the final statement in its effect block. If your operation does not require disposal it might be a SideEffect instead, or a LaunchedEffect if it launches a coroutine that should be managed by the composition.

There is guaranteed to be one call to dispose for every call to effect. Both effect and dispose will always be run on the composition's apply dispatcher and appliers are never run concurrent with themselves, one another, applying changes to the composition tree, or running RememberObserver event callbacks.

@Composable
@NonRestartableComposable
fun DisposableEffect(key1: Any?, key2: Any?, effect: DisposableEffectScope.() -> DisposableEffectResult): Unit

A side effect of composition that must run for any new unique value of key1 or key2 and must be reversed or cleaned up if key1 or key2 changes, or if the DisposableEffect leaves the composition.

A DisposableEffect's key is a value that defines the identity of the DisposableEffect. If a key changes, the DisposableEffect must dispose its current effect and reset by calling effect again. Examples of keys include:

• Observable objects that the effect subscribes to

• Unique request parameters to an operation that must cancel and retry if those parameters change

DisposableEffect may be used to initialize or subscribe to a key and reinitialize when a different key is provided, performing cleanup for the old operation before initializing the new. For example:

import androidx.compose.runtime.Composable
import androidx.compose.runtime.DisposableEffect
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

@Composable
fun UserProfile(userRepository: UserRepository, userRequest: UserDataRequest) {
    var userDataState by remember { mutableStateOf<UserDataState>(UserDataState.Loading) }

    // If either the repository or request change, we must cancel our old data fetch
    // and begin a new data fetch. We will cancel the current data fetch if UserProfile
    // leaves the composition.
    DisposableEffect(userRepository, userRequest) {
        val requestDisposable =
            userRepository.fetchUserData(
                userRequest,
                onSuccess = { response -> userDataState = UserDataState.UserData(response) },
                onError = { throwable ->
                    userDataState = UserDataState.Error(throwable.message)
                }
            )

        onDispose { requestDisposable.dispose() }
    }

    // ...
}

A DisposableEffect must include an onDispose clause as the final statement in its effect block. If your operation does not require disposal it might be a SideEffect instead, or a LaunchedEffect if it launches a coroutine that should be managed by the composition.

There is guaranteed to be one call to dispose for every call to effect. Both effect and dispose will always be run on the composition's apply dispatcher and appliers are never run concurrent with themselves, one another, applying changes to the composition tree, or running RememberObserver event callbacks.

@Composable
@NonRestartableComposable
fun DisposableEffect(
    key1: Any?,
    key2: Any?,
    key3: Any?,
    effect: DisposableEffectScope.() -> DisposableEffectResult
): Unit

A side effect of composition that must run for any new unique value of key1, key2 or key3 and must be reversed or cleaned up if key1, key2 or key3 changes, or if the DisposableEffect leaves the composition.

A DisposableEffect's key is a value that defines the identity of the DisposableEffect. If a key changes, the DisposableEffect must dispose its current effect and reset by calling effect again. Examples of keys include:

• Observable objects that the effect subscribes to

• Unique request parameters to an operation that must cancel and retry if those parameters change

DisposableEffect may be used to initialize or subscribe to a key and reinitialize when a different key is provided, performing cleanup for the old operation before initializing the new. For example:

import androidx.compose.runtime.Composable
import androidx.compose.runtime.DisposableEffect
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

@Composable
fun UserProfile(userRepository: UserRepository, userRequest: UserDataRequest) {
    var userDataState by remember { mutableStateOf<UserDataState>(UserDataState.Loading) }

    // If either the repository or request change, we must cancel our old data fetch
    // and begin a new data fetch. We will cancel the current data fetch if UserProfile
    // leaves the composition.
    DisposableEffect(userRepository, userRequest) {
        val requestDisposable =
            userRepository.fetchUserData(
                userRequest,
                onSuccess = { response -> userDataState = UserDataState.UserData(response) },
                onError = { throwable ->
                    userDataState = UserDataState.Error(throwable.message)
                }
            )

        onDispose { requestDisposable.dispose() }
    }

    // ...
}

A DisposableEffect must include an onDispose clause as the final statement in its effect block. If your operation does not require disposal it might be a SideEffect instead, or a LaunchedEffect if it launches a coroutine that should be managed by the composition.

There is guaranteed to be one call to dispose for every call to effect. Both effect and dispose will always be run on the composition's apply dispatcher and appliers are never run concurrent with themselves, one another, applying changes to the composition tree, or running RememberObserver event callbacks.

@Composable
fun LaunchedEffect(block: suspend CoroutineScope.() -> Unit): Unit

When LaunchedEffect enters the composition it will launch block into the composition's CoroutineContext. The coroutine will be cancelled when the LaunchedEffect leaves the composition.

It is an error to call LaunchedEffect without at least one key parameter.

@Composable
@NonRestartableComposable
fun LaunchedEffect(key1: Any?, block: suspend CoroutineScope.() -> Unit): Unit

When LaunchedEffect enters the composition it will launch block into the composition's CoroutineContext. The coroutine will be cancelled and re-launched when LaunchedEffect is recomposed with a different key1. The coroutine will be cancelled when the LaunchedEffect leaves the composition.

This function should not be used to (re-)launch ongoing tasks in response to callback events by way of storing callback data in MutableState passed to key1. Instead, see rememberCoroutineScope to obtain a CoroutineScope that may be used to launch ongoing jobs scoped to the composition in response to event callbacks.

@Composable
@NonRestartableComposable
fun LaunchedEffect(vararg keys: Any?, block: suspend CoroutineScope.() -> Unit): Unit

When LaunchedEffect enters the composition it will launch block into the composition's CoroutineContext. The coroutine will be cancelled and re-launched when LaunchedEffect is recomposed with any different keys. The coroutine will be cancelled when the LaunchedEffect leaves the composition.

This function should not be used to (re-)launch ongoing tasks in response to callback events by way of storing callback data in MutableState passed to key. Instead, see rememberCoroutineScope to obtain a CoroutineScope that may be used to launch ongoing jobs scoped to the composition in response to event callbacks.

@Composable
@NonRestartableComposable
fun LaunchedEffect(key1: Any?, key2: Any?, block: suspend CoroutineScope.() -> Unit): Unit

When LaunchedEffect enters the composition it will launch block into the composition's CoroutineContext. The coroutine will be cancelled and re-launched when LaunchedEffect is recomposed with a different key1 or key2. The coroutine will be cancelled when the LaunchedEffect leaves the composition.

This function should not be used to (re-)launch ongoing tasks in response to callback events by way of storing callback data in MutableState passed to key. Instead, see rememberCoroutineScope to obtain a CoroutineScope that may be used to launch ongoing jobs scoped to the composition in response to event callbacks.

@Composable
@NonRestartableComposable
fun LaunchedEffect(key1: Any?, key2: Any?, key3: Any?, block: suspend CoroutineScope.() -> Unit): Unit

When LaunchedEffect enters the composition it will launch block into the composition's CoroutineContext. The coroutine will be cancelled and re-launched when LaunchedEffect is recomposed with a different key1, key2 or key3. The coroutine will be cancelled when the LaunchedEffect leaves the composition.

This function should not be used to (re-)launch ongoing tasks in response to callback events by way of storing callback data in MutableState passed to key. Instead, see rememberCoroutineScope to obtain a CoroutineScope that may be used to launch ongoing jobs scoped to the composition in response to event callbacks.

fun PausableComposition(applier: Applier<*>, parent: CompositionContext): PausableComposition

Create a PausableComposition. A PausableComposition can create a PausedComposition which allows pausing and resuming the composition.

@Composable
inline fun <T : Any, E : Applier<*>> ReusableComposeNode(
    noinline factory: () -> T,
    update: @DisallowComposableCalls Updater<T>.() -> Unit
): Unit

Emits a recyclable node into the composition of type T.

This function will throw a runtime exception if E is not a subtype of the applier of the currentComposer.

import androidx.compose.runtime.AbstractApplier
import androidx.compose.runtime.Composable
import androidx.compose.runtime.ComposeNode
import androidx.compose.runtime.Composition
import androidx.compose.runtime.CompositionContext
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

// Provided we have a tree with a node base type like the following
abstract class Node {
    val children = mutableListOf<Node>()
}

// We would implement an Applier class like the following, which would teach compose how to
// manage a tree of Nodes.
class NodeApplier(root: Node) : AbstractApplier<Node>(root) {
    override fun insertTopDown(index: Int, instance: Node) {
        current.children.add(index, instance)
    }

    override fun insertBottomUp(index: Int, instance: Node) {
        // Ignored as the tree is built top-down.
    }

    override fun remove(index: Int, count: Int) {
        current.children.remove(index, count)
    }

    override fun move(from: Int, to: Int, count: Int) {
        current.children.move(from, to, count)
    }

    override fun onClear() {
        root.children.clear()
    }
}

// A function like the following could be created to create a composition provided a root Node.
fun Node.setContent(parent: CompositionContext, content: @Composable () -> Unit): Composition {
    return Composition(NodeApplier(this), parent).apply { setContent(content) }
}

// assuming we have Node sub-classes like "TextNode" and "GroupNode"
class TextNode : Node() {
    var text: String = ""
    var onClick: () -> Unit = {}
}
class GroupNode : Node()

// Composable equivalents could be created
@Composable
fun Text(text: String, onClick: () -> Unit = {}) {
    ComposeNode<TextNode, NodeApplier>(::TextNode) {
        set(text) { this.text = it }
        set(onClick) { this.onClick = it }
    }
}

@Composable
fun Group(content: @Composable () -> Unit) {
    ComposeNode<GroupNode, NodeApplier>(::GroupNode, {}, content)
}

// and then a sample tree could be composed:
fun runApp(root: GroupNode, parent: CompositionContext) {
    root.setContent(parent) {
        var count by remember { mutableStateOf(0) }
        Group {
            Text("Count: $count")
            Text("Increment") { count++ }
        }
    }
}

@Composable
inline fun <T : Any?, E : Applier<*>> ReusableComposeNode(
    noinline factory: () -> T,
    update: @DisallowComposableCalls Updater<T>.() -> Unit,
    content: @Composable () -> Unit
): Unit

Emits a recyclable node into the composition of type T. Nodes emitted inside of content will become children of the emitted node.

This function will throw a runtime exception if E is not a subtype of the applier of the currentComposer.

import androidx.compose.runtime.AbstractApplier
import androidx.compose.runtime.Composable
import androidx.compose.runtime.ComposeNode
import androidx.compose.runtime.Composition
import androidx.compose.runtime.CompositionContext
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

// Provided we have a tree with a node base type like the following
abstract class Node {
    val children = mutableListOf<Node>()
}

// We would implement an Applier class like the following, which would teach compose how to
// manage a tree of Nodes.
class NodeApplier(root: Node) : AbstractApplier<Node>(root) {
    override fun insertTopDown(index: Int, instance: Node) {
        current.children.add(index, instance)
    }

    override fun insertBottomUp(index: Int, instance: Node) {
        // Ignored as the tree is built top-down.
    }

    override fun remove(index: Int, count: Int) {
        current.children.remove(index, count)
    }

    override fun move(from: Int, to: Int, count: Int) {
        current.children.move(from, to, count)
    }

    override fun onClear() {
        root.children.clear()
    }
}

// A function like the following could be created to create a composition provided a root Node.
fun Node.setContent(parent: CompositionContext, content: @Composable () -> Unit): Composition {
    return Composition(NodeApplier(this), parent).apply { setContent(content) }
}

// assuming we have Node sub-classes like "TextNode" and "GroupNode"
class TextNode : Node() {
    var text: String = ""
    var onClick: () -> Unit = {}
}
class GroupNode : Node()

// Composable equivalents could be created
@Composable
fun Text(text: String, onClick: () -> Unit = {}) {
    ComposeNode<TextNode, NodeApplier>(::TextNode) {
        set(text) { this.text = it }
        set(onClick) { this.onClick = it }
    }
}

@Composable
fun Group(content: @Composable () -> Unit) {
    ComposeNode<GroupNode, NodeApplier>(::GroupNode, {}, content)
}

// and then a sample tree could be composed:
fun runApp(root: GroupNode, parent: CompositionContext) {
    root.setContent(parent) {
        var count by remember { mutableStateOf(0) }
        Group {
            Text("Count: $count")
            Text("Increment") { count++ }
        }
    }
}

@Composable
@ExplicitGroupsComposable
inline fun <T : Any?, E : Applier<*>> ReusableComposeNode(
    noinline factory: () -> T,
    update: @DisallowComposableCalls Updater<T>.() -> Unit,
    noinline skippableUpdate: @Composable SkippableUpdater<T>.() -> Unit,
    content: @Composable () -> Unit
): Unit

Emits a recyclable node into the composition of type T. Nodes emitted inside of content will become children of the emitted node.

This function will throw a runtime exception if E is not a subtype of the applier of the currentComposer.

import androidx.compose.runtime.AbstractApplier
import androidx.compose.runtime.Composable
import androidx.compose.runtime.ComposeNode
import androidx.compose.runtime.Composition
import androidx.compose.runtime.CompositionContext
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

// Provided we have a tree with a node base type like the following
abstract class Node {
    val children = mutableListOf<Node>()
}

// We would implement an Applier class like the following, which would teach compose how to
// manage a tree of Nodes.
class NodeApplier(root: Node) : AbstractApplier<Node>(root) {
    override fun insertTopDown(index: Int, instance: Node) {
        current.children.add(index, instance)
    }

    override fun insertBottomUp(index: Int, instance: Node) {
        // Ignored as the tree is built top-down.
    }

    override fun remove(index: Int, count: Int) {
        current.children.remove(index, count)
    }

    override fun move(from: Int, to: Int, count: Int) {
        current.children.move(from, to, count)
    }

    override fun onClear() {
        root.children.clear()
    }
}

// A function like the following could be created to create a composition provided a root Node.
fun Node.setContent(parent: CompositionContext, content: @Composable () -> Unit): Composition {
    return Composition(NodeApplier(this), parent).apply { setContent(content) }
}

// assuming we have Node sub-classes like "TextNode" and "GroupNode"
class TextNode : Node() {
    var text: String = ""
    var onClick: () -> Unit = {}
}
class GroupNode : Node()

// Composable equivalents could be created
@Composable
fun Text(text: String, onClick: () -> Unit = {}) {
    ComposeNode<TextNode, NodeApplier>(::TextNode) {
        set(text) { this.text = it }
        set(onClick) { this.onClick = it }
    }
}

@Composable
fun Group(content: @Composable () -> Unit) {
    ComposeNode<GroupNode, NodeApplier>(::GroupNode, {}, content)
}

// and then a sample tree could be composed:
fun runApp(root: GroupNode, parent: CompositionContext) {
    root.setContent(parent) {
        var count by remember { mutableStateOf(0) }
        Group {
            Text("Count: $count")
            Text("Increment") { count++ }
        }
    }
}

fun ReusableComposition(applier: Applier<*>, parent: CompositionContext): ReusableComposition

This method is the way to initiate a reusable composition. parent can be provided to make the composition behave as a sub-composition of the parent. If composition does not have a parent, Recomposer instance should be provided.

It is important to call Composition.dispose when composition is no longer needed in order to release resources.

@Composable
inline fun ReusableContent(key: Any?, content: @Composable () -> Unit): Unit

A utility function to mark a composition as supporting recycling. If the key changes the composition is replaced by a new composition (as would happen for key) but reusable nodes that are emitted by ReusableComposeNode are reused.

@Composable
@ExplicitGroupsComposable
inline fun ReusableContentHost(
    active: Boolean,
    crossinline content: @Composable () -> Unit
): Unit

An optional utility function used when hosting ReusableContent. If active is false the content is treated as if it is deleted by removing all remembered objects from the composition but the node produced for the tree are not removed. When the composition later becomes active then the nodes are able to be reused inside ReusableContent content without requiring the remembered state of the composition's lifetime being arbitrarily extended.

@Composable
@NonRestartableComposable
@ExplicitGroupsComposable
fun SideEffect(effect: () -> Unit): Unit

Schedule effect to run when the current composition completes successfully and applies changes. SideEffect can be used to apply side effects to objects managed by the composition that are not backed by snapshots so as not to leave those objects in an inconsistent state if the current composition operation fails.

effect will always be run on the composition's apply dispatcher and appliers are never run concurrent with themselves, one another, applying changes to the composition tree, or running RememberObserver event callbacks. SideEffects are always run after RememberObserver event callbacks.

A SideEffect runs after every recomposition. To launch an ongoing task spanning potentially many recompositions, see LaunchedEffect. To manage an event subscription or other object lifecycle, see DisposableEffect.

@TestOnly
fun clearCompositionErrors(): Unit

Clears current composition errors in hot reload mode. Test-only API, not for use in production.

fun <T : Any?> compositionLocalOf(
    policy: SnapshotMutationPolicy<T> = structuralEqualityPolicy(),
    defaultFactory: () -> T
): ProvidableCompositionLocal<T>

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.

fun <T : Any?> compositionLocalWithComputedDefaultOf(defaultComputation: CompositionLocalAccessorScope.() -> T): ProvidableCompositionLocal<T>

Create a CompositionLocal that behaves like it was provided using ProvidableCompositionLocal.providesComputed by default. If a value is provided using ProvidableCompositionLocal.provides it behaves as if the CompositionLocal was produced by calling compositionLocalOf.

In other words, a CompositionLocal produced by can be provided identically to CompositionLocal created with compositionLocalOf with the only difference is how it behaves when the value is not provided. For a compositionLocalOf the default value is returned. If no default value has be computed for CompositionLocal the default computation is called.

The lambda passed to compositionLocalWithComputedDefaultOf will be invoked every time the CompositionLocal.current is evaluated for the composition local and computes its value based on the current value of the locals referenced in the lambda at the time CompositionLocal.current is evaluated. This allows providing values that can be derived from other locals. For example, if accent colors can be calculated from a single base color, the accent colors can be provided as computed composition locals. Providing a new base color would automatically update all the accent colors.

import androidx.compose.runtime.compositionLocalOf
import androidx.compose.runtime.compositionLocalWithComputedDefaultOf

val LocalBaseValue = compositionLocalOf { 10 }
val LocalLargerValue = compositionLocalWithComputedDefaultOf {
    LocalBaseValue.currentValue + 10
}

import androidx.compose.runtime.Composable
import androidx.compose.runtime.CompositionLocalProvider
import androidx.compose.runtime.compositionLocalOf
import androidx.compose.runtime.compositionLocalWithComputedDefaultOf

val LocalValue = compositionLocalOf { 10 }
val LocalLargerValue = compositionLocalOf { 12 }
val LocalComputedValue = compositionLocalWithComputedDefaultOf { LocalValue.currentValue + 4 }

// In this example `LocalLargerValue` needs to be re-provided
// whenever `LocalValue` is provided to keep its value larger
// then `LocalValue`. However, `LocalComputedValue` does not
// need to be re-provided to stay larger than `LocalValue` as
// it is calculated based on the currently provided value for
// `LocalValue`. Whenever `LocalValue` is provided the value
// of `LocalComputedValue` is computed based on the currently
// provided value for `LocalValue`.

@Composable
fun App() {
    // Value is 10, the default value for LocalValue
    val value = LocalValue.current
    // Value is 12, the default value
    val largerValue = LocalLargerValue.current
    // Value is computed to be 14
    val computedValue = LocalComputedValue.current
    CompositionLocalProvider(LocalValue provides 20) {
        // Value is 20 provided above
        val nestedValue = LocalValue.current
        // Value is still 12 as an updated value was not re-provided
        val nestedLargerValue = LocalLargerValue.current
        // Values is computed to be 24; LocalValue.current + 4
        val nestedComputedValue = LocalComputedValue.current
        CompositionLocalProvider(LocalLargerValue provides LocalValue.current + 2) {
            // Value is 22 provided above
            val newLargerValue = LocalLargerValue.current

            CompositionLocalProvider(LocalValue provides 50) {
                // Value is now 50 provided above
                val finalValue = LocalValue.current
                // Value is still 22
                val finalLargerValue = LocalLargerValue.current
                // Value is now computed to be 54
                val finalComputed = LocalComputedValue.current
            }
        }
    }
}

@TestOnly
fun currentCompositionErrors(): List<Pair<Exception, Boolean>>

Get list of errors captured in composition. This list is only available when recomposer is in hot reload mode. Test-only API, not for use in production.

@StateFactoryMarker
fun <T : Any?> derivedStateOf(calculation: () -> T): State<T>

Creates a State object whose State.value is the result of calculation. The result of calculation will be cached in such a way that calling State.value repeatedly will not cause calculation to be executed multiple times, but reading State.value will cause all State objects that got read during the calculation to be read in the current Snapshot, meaning that this will correctly subscribe to the derived state objects if the value is being read in an observed context such as a Composable function. Derived states without mutation policy trigger updates on each dependency change. To avoid invalidation on update, provide suitable SnapshotMutationPolicy through derivedStateOf overload.

import androidx.compose.material.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.State
import androidx.compose.runtime.derivedStateOf
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

@Composable
fun CountDisplay(count: State<Int>) {
    Text("Count: ${count.value}")
}

@Composable
fun Example() {
    var a by remember { mutableStateOf(0) }
    var b by remember { mutableStateOf(0) }
    val sum = remember { derivedStateOf { a + b } }
    // Changing either a or b will cause CountDisplay to recompose but not trigger Example
    // to recompose.
    CountDisplay(sum)
}

@StateFactoryMarker
fun <T : Any?> derivedStateOf(
    policy: SnapshotMutationPolicy<T>,
    calculation: () -> T
): State<T>

Creates a State object whose State.value is the result of calculation. The result of calculation will be cached in such a way that calling State.value repeatedly will not cause calculation to be executed multiple times, but reading State.value will cause all State objects that got read during the calculation to be read in the current Snapshot, meaning that this will correctly subscribe to the derived state objects if the value is being read in an observed context such as a Composable function.

import androidx.compose.material.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.State
import androidx.compose.runtime.derivedStateOf
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

@Composable
fun CountDisplay(count: State<Int>) {
    Text("Count: ${count.value}")
}

@Composable
fun Example() {
    var a by remember { mutableStateOf(0) }
    var b by remember { mutableStateOf(0) }
    val sum = remember { derivedStateOf { a + b } }
    // Changing either a or b will cause CountDisplay to recompose but not trigger Example
    // to recompose.
    CountDisplay(sum)
}

@TestOnly
fun invalidateGroupsWithKey(key: Int): Unit

Invalidates composed groups with the given key. Calling this method switches recomposer into hot reload mode. Test-only API, not for use in production.

@ComposeCompilerApi
fun isTraceInProgress(): Boolean

Internal tracing API.

Should be called without thread synchronization with occasional information loss.

@Composable
inline fun <T : Any?> key(vararg keys: Any?, block: @Composable () -> T): T

key is a utility composable that is used to "group" or "key" a block of execution inside of a composition. This is sometimes needed for correctness inside of control-flow that may cause a given composable invocation to execute more than once during composition.

The value for a key does not need to be globally unique, and needs only be unique amongst the invocations of key at that point in composition.

For instance, consider the following example:

import androidx.compose.runtime.key

for (user in users) {
    key(user.id) { UserPreview(user = user) }
}

for (user in users.filter { isAdmin }) {
    key(user.id) { Friend(friend = user) }
}

Even though there are users with the same id composed in both the top and the bottom loop, because they are different calls to key, there is no need to create compound keys.

The key must be unique for each element in the collection, however, or children and local state might be reused in unintended ways.

For instance, consider the following example:

import androidx.compose.runtime.key

for ((child, parent) in relationships) {
    key(parent.id) {
        User(user = child)
        User(user = parent)
    }
}

This example assumes that parent.id is a unique key for each item in the collection, but this is only true if it is fair to assume that a parent will only ever have a single child, which may not be the case. Instead, it may be more correct to do the following:

import androidx.compose.runtime.key

for ((child, parent) in relationships) {
    key(parent.id to child.id) {
        User(user = child)
        User(user = parent)
    }
}

A compound key can be created by passing in multiple arguments:

import androidx.compose.runtime.State
import androidx.compose.runtime.key
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

for (element in elements) {
    val selected by key(element.id, parentId) { remember { mutableStateOf(false) } }
    ListItem(item = element, selected = selected)
}

fun movableContentOf(content: @Composable () -> Unit): @Composable () -> Unit

Convert a lambda into one that moves the remembered state and nodes created in a previous call to the new location it is called.

Tracking compositions can be used to produce a composable that moves its content between a row and a column based on a parameter, such as,

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.runtime.movableContentOf
import androidx.compose.runtime.remember

val movableContent = remember(content) { movableContentOf(content) }

if (vertical) {
    Column { movableContent() }
} else {
    Row { movableContent() }
}

Or they can be used to ensure the composition state tracks with a model as moves in the layout, such as,

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.runtime.Composable
import androidx.compose.runtime.movableContentOf
import androidx.compose.runtime.remember

val itemMap = remember { mutableMapOf<Item, @Composable () -> Unit>() }
val movableItems =
    items.map { item -> itemMap.getOrPut(item) { movableContentOf { ItemView(item) } } }

val itemsPerColumn = 10
val columns = items.size / itemsPerColumn + (if (items.size % itemsPerColumn == 0) 0 else 1)
Row {
    repeat(columns) { column ->
        Column {
            val base = column * itemsPerColumn
            val end = minOf(base + itemsPerColumn, items.size)
            for (index in base until end) {
                movableItems[index]()
            }
        }
    }
}

fun <P : Any?> movableContentOf(content: @Composable (P) -> Unit): @Composable (P) -> Unit

Convert a lambda into one that moves the remembered state and nodes created in a previous call to the new location it is called.

Tracking compositions can be used to produce a composable that moves its content between a row and a column based on a parameter, such as,

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.runtime.movableContentOf
import androidx.compose.runtime.remember

val movableContent = remember(content) { movableContentOf(content) }

if (vertical) {
    Column { movableContent() }
} else {
    Row { movableContent() }
}

Or they can be used to ensure the composition state tracks with a model as moves in the layout, such as,

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.runtime.Composable
import androidx.compose.runtime.movableContentOf
import androidx.compose.runtime.remember

val itemMap = remember { mutableMapOf<Item, @Composable () -> Unit>() }
val movableItems =
    items.map { item -> itemMap.getOrPut(item) { movableContentOf { ItemView(item) } } }

val itemsPerColumn = 10
val columns = items.size / itemsPerColumn + (if (items.size % itemsPerColumn == 0) 0 else 1)
Row {
    repeat(columns) { column ->
        Column {
            val base = column * itemsPerColumn
            val end = minOf(base + itemsPerColumn, items.size)
            for (index in base until end) {
                movableItems[index]()
            }
        }
    }
}

fun <P1 : Any?, P2 : Any?> movableContentOf(content: @Composable (P1, P2) -> Unit): @Composable (P1, P2) -> Unit

Convert a lambda into one that moves the remembered state and nodes created in a previous call to the new location it is called.

Tracking compositions can be used to produce a composable that moves its content between a row and a column based on a parameter, such as,

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.runtime.movableContentOf
import androidx.compose.runtime.remember

val movableContent = remember(content) { movableContentOf(content) }

if (vertical) {
    Column { movableContent() }
} else {
    Row { movableContent() }
}

Or they can be used to ensure the composition state tracks with a model as moves in the layout, such as,

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.runtime.Composable
import androidx.compose.runtime.movableContentOf
import androidx.compose.runtime.remember

val itemMap = remember { mutableMapOf<Item, @Composable () -> Unit>() }
val movableItems =
    items.map { item -> itemMap.getOrPut(item) { movableContentOf { ItemView(item) } } }

val itemsPerColumn = 10
val columns = items.size / itemsPerColumn + (if (items.size % itemsPerColumn == 0) 0 else 1)
Row {
    repeat(columns) { column ->
        Column {
            val base = column * itemsPerColumn
            val end = minOf(base + itemsPerColumn, items.size)
            for (index in base until end) {
                movableItems[index]()
            }
        }
    }
}

fun <P1 : Any?, P2 : Any?, P3 : Any?> movableContentOf(
    content: @Composable (P1, P2, P3) -> Unit
): @Composable (P1, P2, P3) -> Unit

Convert a lambda into one that moves the remembered state and nodes created in a previous call to the new location it is called.

Tracking compositions can be used to produce a composable that moves its content between a row and a column based on a parameter, such as,

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.runtime.movableContentOf
import androidx.compose.runtime.remember

val movableContent = remember(content) { movableContentOf(content) }

if (vertical) {
    Column { movableContent() }
} else {
    Row { movableContent() }
}

Or they can be used to ensure the composition state tracks with a model as moves in the layout, such as,

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.runtime.Composable
import androidx.compose.runtime.movableContentOf
import androidx.compose.runtime.remember

val itemMap = remember { mutableMapOf<Item, @Composable () -> Unit>() }
val movableItems =
    items.map { item -> itemMap.getOrPut(item) { movableContentOf { ItemView(item) } } }

val itemsPerColumn = 10
val columns = items.size / itemsPerColumn + (if (items.size % itemsPerColumn == 0) 0 else 1)
Row {
    repeat(columns) { column ->
        Column {
            val base = column * itemsPerColumn
            val end = minOf(base + itemsPerColumn, items.size)
            for (index in base until end) {
                movableItems[index]()
            }
        }
    }
}

fun <P1 : Any?, P2 : Any?, P3 : Any?, P4 : Any?> movableContentOf(
    content: @Composable (P1, P2, P3, P4) -> Unit
): @Composable (P1, P2, P3, P4) -> Unit

Convert a lambda into one that moves the remembered state and nodes created in a previous call to the new location it is called.

Tracking compositions can be used to produce a composable that moves its content between a row and a column based on a parameter, such as,

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.runtime.movableContentOf
import androidx.compose.runtime.remember

val movableContent = remember(content) { movableContentOf(content) }

if (vertical) {
    Column { movableContent() }
} else {
    Row { movableContent() }
}

Or they can be used to ensure the composition state tracks with a model as moves in the layout, such as,

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.runtime.Composable
import androidx.compose.runtime.movableContentOf
import androidx.compose.runtime.remember

val itemMap = remember { mutableMapOf<Item, @Composable () -> Unit>() }
val movableItems =
    items.map { item -> itemMap.getOrPut(item) { movableContentOf { ItemView(item) } } }

val itemsPerColumn = 10
val columns = items.size / itemsPerColumn + (if (items.size % itemsPerColumn == 0) 0 else 1)
Row {
    repeat(columns) { column ->
        Column {
            val base = column * itemsPerColumn
            val end = minOf(base + itemsPerColumn, items.size)
            for (index in base until end) {
                movableItems[index]()
            }
        }
    }
}

fun <R : Any?> movableContentWithReceiverOf(content: @Composable R.() -> Unit): @Composable R.() -> Unit

Convert a lambda with a receiver into one that moves the remembered state and nodes created in a previous call to the new location it is called.

Tracking compositions can be used to produce a composable that moves its content between a row and a column based on a parameter, such as,

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.runtime.movableContentOf
import androidx.compose.runtime.remember

val movableContent = remember(content) { movableContentOf(content) }

if (vertical) {
    Column { movableContent() }
} else {
    Row { movableContent() }
}

Or they can be used to ensure the composition state tracks with a model as moves in the layout, such as,

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.runtime.Composable
import androidx.compose.runtime.movableContentOf
import androidx.compose.runtime.remember

val itemMap = remember { mutableMapOf<Item, @Composable () -> Unit>() }
val movableItems =
    items.map { item -> itemMap.getOrPut(item) { movableContentOf { ItemView(item) } } }

val itemsPerColumn = 10
val columns = items.size / itemsPerColumn + (if (items.size % itemsPerColumn == 0) 0 else 1)
Row {
    repeat(columns) { column ->
        Column {
            val base = column * itemsPerColumn
            val end = minOf(base + itemsPerColumn, items.size)
            for (index in base until end) {
                movableItems[index]()
            }
        }
    }
}

fun <R : Any?, P : Any?> movableContentWithReceiverOf(content: @Composable R.(P) -> Unit): @Composable R.(P) -> Unit

Convert a lambda with a receiver into one that moves the remembered state and nodes created in a previous call to the new location it is called.

Tracking compositions can be used to produce a composable that moves its content between a row and a column based on a parameter, such as,

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.runtime.movableContentOf
import androidx.compose.runtime.remember

val movableContent = remember(content) { movableContentOf(content) }

if (vertical) {
    Column { movableContent() }
} else {
    Row { movableContent() }
}

Or they can be used to ensure the composition state tracks with a model as moves in the layout, such as,

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.runtime.Composable
import androidx.compose.runtime.movableContentOf
import androidx.compose.runtime.remember

val itemMap = remember { mutableMapOf<Item, @Composable () -> Unit>() }
val movableItems =
    items.map { item -> itemMap.getOrPut(item) { movableContentOf { ItemView(item) } } }

val itemsPerColumn = 10
val columns = items.size / itemsPerColumn + (if (items.size % itemsPerColumn == 0) 0 else 1)
Row {
    repeat(columns) { column ->
        Column {
            val base = column * itemsPerColumn
            val end = minOf(base + itemsPerColumn, items.size)
            for (index in base until end) {
                movableItems[index]()
            }
        }
    }
}

fun <R : Any?, P1 : Any?, P2 : Any?> movableContentWithReceiverOf(
    content: @Composable R.(P1, P2) -> Unit
): @Composable R.(P1, P2) -> Unit

Convert a lambda with a receiver into one that moves the remembered state and nodes created in a previous call to the new location it is called.

Tracking compositions can be used to produce a composable that moves its content between a row and a column based on a parameter, such as,

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.runtime.movableContentOf
import androidx.compose.runtime.remember

val movableContent = remember(content) { movableContentOf(content) }

if (vertical) {
    Column { movableContent() }
} else {
    Row { movableContent() }
}

Or they can be used to ensure the composition state tracks with a model as moves in the layout, such as,

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.runtime.Composable
import androidx.compose.runtime.movableContentOf
import androidx.compose.runtime.remember

val itemMap = remember { mutableMapOf<Item, @Composable () -> Unit>() }
val movableItems =
    items.map { item -> itemMap.getOrPut(item) { movableContentOf { ItemView(item) } } }

val itemsPerColumn = 10
val columns = items.size / itemsPerColumn + (if (items.size % itemsPerColumn == 0) 0 else 1)
Row {
    repeat(columns) { column ->
        Column {
            val base = column * itemsPerColumn
            val end = minOf(base + itemsPerColumn, items.size)
            for (index in base until end) {
                movableItems[index]()
            }
        }
    }
}

fun <R : Any?, P1 : Any?, P2 : Any?, P3 : Any?> movableContentWithReceiverOf(
    content: @Composable R.(P1, P2, P3) -> Unit
): @Composable R.(P1, P2, P3) -> Unit

Convert a lambda with a receiver into one that moves the remembered state and nodes created in a previous call to the new location it is called.

Tracking compositions can be used to produce a composable that moves its content between a row and a column based on a parameter, such as,

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.runtime.movableContentOf
import androidx.compose.runtime.remember

val movableContent = remember(content) { movableContentOf(content) }

if (vertical) {
    Column { movableContent() }
} else {
    Row { movableContent() }
}

Or they can be used to ensure the composition state tracks with a model as moves in the layout, such as,

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.runtime.Composable
import androidx.compose.runtime.movableContentOf
import androidx.compose.runtime.remember

val itemMap = remember { mutableMapOf<Item, @Composable () -> Unit>() }
val movableItems =
    items.map { item -> itemMap.getOrPut(item) { movableContentOf { ItemView(item) } } }

val itemsPerColumn = 10
val columns = items.size / itemsPerColumn + (if (items.size % itemsPerColumn == 0) 0 else 1)
Row {
    repeat(columns) { column ->
        Column {
            val base = column * itemsPerColumn
            val end = minOf(base + itemsPerColumn, items.size)
            for (index in base until end) {
                movableItems[index]()
            }
        }
    }
}

@StateFactoryMarker
fun mutableDoubleStateOf(value: Double): MutableDoubleState

Return a new MutableDoubleState initialized with the passed in value

The MutableDoubleState class is a single value holder whose reads and writes are observed by Compose. Additionally, writes to it are transacted as part of the Snapshot system. On the JVM, values are stored in memory as the primitive double type, avoiding the autoboxing that occurs when using MutableState<Double>.

@StateFactoryMarker
fun mutableFloatStateOf(value: Float): MutableFloatState

Return a new MutableFloatState initialized with the passed in value

The MutableFloatState class is a single value holder whose reads and writes are observed by Compose. Additionally, writes to it are transacted as part of the Snapshot system. On the JVM, values are stored in memory as the primitive float type, avoiding the autoboxing that occurs when using MutableState<Float>.

@StateFactoryMarker
fun mutableIntStateOf(value: Int): MutableIntState

Return a new MutableIntState initialized with the passed in value

The MutableIntState class is a single value holder whose reads and writes are observed by Compose. Additionally, writes to it are transacted as part of the Snapshot system. On the JVM, values are stored in memory as the primitive int type, avoiding the autoboxing that occurs when using MutableState<Int>.

@StateFactoryMarker
fun mutableLongStateOf(value: Long): MutableLongState

Return a new MutableLongState initialized with the passed in value

The MutableLongState class is a single value holder whose reads and writes are observed by Compose. Additionally, writes to it are transacted as part of the Snapshot system. On the JVM, values are stored in memory as the primitive long type, avoiding the autoboxing that occurs when using MutableState<Long>.

@StateFactoryMarker
fun <T : Any?> mutableStateListOf(): SnapshotStateList<T>

Create a instance of MutableList that is observable and can be snapshot.

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.text.BasicTextField
import androidx.compose.material.Button
import androidx.compose.material.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.mutableStateListOf
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

@Composable
fun Names() {
    var name by remember { mutableStateOf("user") }
    val names = remember { mutableStateListOf<String>() }

    Column {
        Row {
            BasicTextField(value = name, onValueChange = { name = it })
            Button(onClick = { names.add(name) }) { Text("Add") }
        }
        Text("Added names:")
        Column {
            for (addedName in names) {
                Text(addedName)
            }
        }
    }
}

@StateFactoryMarker
fun <T : Any?> mutableStateListOf(vararg elements: T): SnapshotStateList<T>

Create an instance of MutableList that is observable and can be snapshot.

@StateFactoryMarker
fun <K : Any?, V : Any?> mutableStateMapOf(): SnapshotStateMap<K, V>

Create a instance of MutableMap that is observable and can be snapshot.

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.text.BasicTextField
import androidx.compose.material.Button
import androidx.compose.material.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.mutableStateMapOf
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

@Composable
fun NamesAndAges() {
    var name by remember { mutableStateOf("name") }
    var saying by remember { mutableStateOf("saying") }
    val sayings = remember {
        mutableStateMapOf(
            "Caesar" to "Et tu, Brute?",
            "Hamlet" to "To be or not to be",
            "Richard III" to "My kingdom for a horse"
        )
    }

    Column {
        Row {
            BasicTextField(value = name, onValueChange = { name = it })
            BasicTextField(value = saying, onValueChange = { saying = it })
            Button(onClick = { sayings[name] = saying }) { Text("Add") }
            Button(onClick = { sayings.remove(name) }) { Text("Remove") }
        }
        Text("Sayings:")
        Column {
            for (entry in sayings) {
                Text("${entry.key} says '${entry.value}'")
            }
        }
    }
}

@StateFactoryMarker
fun <K : Any?, V : Any?> mutableStateMapOf(vararg pairs: Pair<K, V>): SnapshotStateMap<K, V>

Create a instance of MutableMap that is observable and can be snapshot.

@StateFactoryMarker
fun <T : Any?> mutableStateOf(
    value: T,
    policy: SnapshotMutationPolicy<T> = structuralEqualityPolicy()
): MutableState<T>

Return a new MutableState initialized with the passed in value

The MutableState class is a single value holder whose reads and writes are observed by Compose. Additionally, writes to it are transacted as part of the Snapshot system.

import androidx.compose.material.Button
import androidx.compose.material.Text
import androidx.compose.runtime.State
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

val count = remember { mutableStateOf(0) }

Text(text = "You clicked ${count.value} times")
Button(onClick = { count.value++ }) { Text("Click me") }

import androidx.compose.material.Button
import androidx.compose.material.Text
import androidx.compose.runtime.State
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

val (count, setCount) = remember { mutableStateOf(0) }

Text(text = "You clicked $count times")
Button(onClick = { setCount(count + 1) }) { Text("Click me") }

import androidx.compose.runtime.Composable
import androidx.compose.runtime.DisposableEffect
import androidx.compose.runtime.State
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

@Composable
fun observeUser(userId: Int): User? {
    val user = remember(userId) { mutableStateOf<User?>(null) }
    DisposableEffect(userId) {
        val subscription = UserAPI.subscribeToUser(userId) { user.value = it }
        onDispose { subscription.unsubscribe() }
    }
    return user.value
}

import androidx.compose.foundation.text.BasicTextField
import androidx.compose.material.Button
import androidx.compose.material.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

@Composable
fun LoginScreen() {
    var username by remember { mutableStateOf("user") }
    var password by remember { mutableStateOf("pass") }

    fun login() = Api.login(username, password)

    BasicTextField(value = username, onValueChange = { username = it })
    BasicTextField(value = password, onValueChange = { password = it })
    Button(onClick = { login() }) { Text("Login") }
}

@StateFactoryMarker
fun <T : Any?> mutableStateSetOf(): SnapshotStateSet<T>

Create a instance of MutableSet that is observable and can be snapshot.

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.text.BasicTextField
import androidx.compose.material.Button
import androidx.compose.material.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.mutableStateListOf
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

@Composable
fun Names() {
    var name by remember { mutableStateOf("user") }
    val names = remember { mutableStateListOf<String>() }

    Column {
        Row {
            BasicTextField(value = name, onValueChange = { name = it })
            Button(onClick = { names.add(name) }) { Text("Add") }
        }
        Text("Added names:")
        Column {
            for (addedName in names) {
                Text(addedName)
            }
        }
    }
}

@StateFactoryMarker
fun <T : Any?> mutableStateSetOf(vararg elements: T): SnapshotStateSet<T>

Create an instance of MutableSet that is observable and can be snapshot.

fun <T : Any?> neverEqualPolicy(): SnapshotMutationPolicy<T>

A policy never treat values of a MutableState as equivalent.

Setting MutableState.value will always be considered a change. When applying a MutableSnapshot that changes the state will always conflict with other snapshots that change the same state.

@Composable
fun <T : Any?> produceState(initialValue: T, producer: suspend ProduceStateScope<T>.() -> Unit): State<T>

Return an observable snapshot State that produces values over time without a defined data source.

producer is launched when produceState enters the composition and is cancelled when produceState leaves the composition. producer should use ProduceStateScope.value to set new values on the returned State.

The returned State conflates values; no change will be observable if ProduceStateScope.value is used to set a value that is equal to its old value, and observers may only see the latest value if several values are set in rapid succession.

produceState may be used to observe either suspending or non-suspending sources of external data, for example:

import androidx.compose.foundation.layout.Column
import androidx.compose.runtime.produceState

val uiState by
    produceState<UiState<List<Person>>>(UiState.Loading, viewModel) {
        viewModel.people.map { UiState.Data(it) }.collect { value = it }
    }

when (val state = uiState) {
    is UiState.Loading -> Text("Loading...")
    is UiState.Data ->
        Column {
            for (person in state.data) {
                Text("Hello, ${person.name}")
            }
        }
}

import androidx.compose.runtime.produceState

val currentPerson by
    produceState<Person?>(null, viewModel) {
        val disposable = viewModel.registerPersonObserver { person -> value = person }

        awaitDispose { disposable.dispose() }
    }

@Composable
fun <T : Any?> produceState(initialValue: T, key1: Any?, producer: suspend ProduceStateScope<T>.() -> Unit): State<T>

Return an observable snapshot State that produces values over time from key1.

producer is launched when produceState enters the composition and is cancelled when produceState leaves the composition. If key1 changes, a running producer will be cancelled and re-launched for the new source. producer should use ProduceStateScope.value to set new values on the returned State.

The returned State conflates values; no change will be observable if ProduceStateScope.value is used to set a value that is equal to its old value, and observers may only see the latest value if several values are set in rapid succession.

produceState may be used to observe either suspending or non-suspending sources of external data, for example:

import androidx.compose.foundation.layout.Column
import androidx.compose.runtime.produceState

val uiState by
    produceState<UiState<List<Person>>>(UiState.Loading, viewModel) {
        viewModel.people.map { UiState.Data(it) }.collect { value = it }
    }

when (val state = uiState) {
    is UiState.Loading -> Text("Loading...")
    is UiState.Data ->
        Column {
            for (person in state.data) {
                Text("Hello, ${person.name}")
            }
        }
}

import androidx.compose.runtime.produceState

val currentPerson by
    produceState<Person?>(null, viewModel) {
        val disposable = viewModel.registerPersonObserver { person -> value = person }

        awaitDispose { disposable.dispose() }
    }

@Composable
fun <T : Any?> produceState(
    initialValue: T,
    vararg keys: Any?,
    producer: suspend ProduceStateScope<T>.() -> Unit
): State<T>

Return an observable snapshot State that produces values over time from keys.

producer is launched when produceState enters the composition and is cancelled when produceState leaves the composition. If keys change, a running producer will be cancelled and re-launched for the new source. producer should use ProduceStateScope.value to set new values on the returned State.

The returned State conflates values; no change will be observable if ProduceStateScope.value is used to set a value that is equal to its old value, and observers may only see the latest value if several values are set in rapid succession.

produceState may be used to observe either suspending or non-suspending sources of external data, for example:

import androidx.compose.foundation.layout.Column
import androidx.compose.runtime.produceState

val uiState by
    produceState<UiState<List<Person>>>(UiState.Loading, viewModel) {
        viewModel.people.map { UiState.Data(it) }.collect { value = it }
    }

when (val state = uiState) {
    is UiState.Loading -> Text("Loading...")
    is UiState.Data ->
        Column {
            for (person in state.data) {
                Text("Hello, ${person.name}")
            }
        }
}

import androidx.compose.runtime.produceState

val currentPerson by
    produceState<Person?>(null, viewModel) {
        val disposable = viewModel.registerPersonObserver { person -> value = person }

        awaitDispose { disposable.dispose() }
    }

@Composable
fun <T : Any?> produceState(
    initialValue: T,
    key1: Any?,
    key2: Any?,
    producer: suspend ProduceStateScope<T>.() -> Unit
): State<T>

Return an observable snapshot State that produces values over time from key1 and key2.

producer is launched when produceState enters the composition and is cancelled when produceState leaves the composition. If key1 or key2 change, a running producer will be cancelled and re-launched for the new source. producer should use ProduceStateScope.value to set new values on the returned State.

The returned State conflates values; no change will be observable if ProduceStateScope.value is used to set a value that is equal to its old value, and observers may only see the latest value if several values are set in rapid succession.

produceState may be used to observe either suspending or non-suspending sources of external data, for example:

import androidx.compose.foundation.layout.Column
import androidx.compose.runtime.produceState

val uiState by
    produceState<UiState<List<Person>>>(UiState.Loading, viewModel) {
        viewModel.people.map { UiState.Data(it) }.collect { value = it }
    }

when (val state = uiState) {
    is UiState.Loading -> Text("Loading...")
    is UiState.Data ->
        Column {
            for (person in state.data) {
                Text("Hello, ${person.name}")
            }
        }
}

import androidx.compose.runtime.produceState

val currentPerson by
    produceState<Person?>(null, viewModel) {
        val disposable = viewModel.registerPersonObserver { person -> value = person }

        awaitDispose { disposable.dispose() }
    }

@Composable
fun <T : Any?> produceState(
    initialValue: T,
    key1: Any?,
    key2: Any?,
    key3: Any?,
    producer: suspend ProduceStateScope<T>.() -> Unit
): State<T>

Return an observable snapshot State that produces values over time from key1, key2 and key3.

producer is launched when produceState enters the composition and is cancelled when produceState leaves the composition. If key1, key2 or key3 change, a running producer will be cancelled and re-launched for the new source. [producer should use ProduceStateScope.value to set new values on the returned State.

The returned State conflates values; no change will be observable if ProduceStateScope.value is used to set a value that is equal to its old value, and observers may only see the latest value if several values are set in rapid succession.

produceState may be used to observe either suspending or non-suspending sources of external data, for example:

import androidx.compose.foundation.layout.Column
import androidx.compose.runtime.produceState

val uiState by
    produceState<UiState<List<Person>>>(UiState.Loading, viewModel) {
        viewModel.people.map { UiState.Data(it) }.collect { value = it }
    }

when (val state = uiState) {
    is UiState.Loading -> Text("Loading...")
    is UiState.Data ->
        Column {
            for (person in state.data) {
                Text("Hello, ${person.name}")
            }
        }
}

import androidx.compose.runtime.produceState

val currentPerson by
    produceState<Person?>(null, viewModel) {
        val disposable = viewModel.registerPersonObserver { person -> value = person }

        awaitDispose { disposable.dispose() }
    }

fun <T : Any?> referentialEqualityPolicy(): SnapshotMutationPolicy<T>

A policy to treat values of a MutableState as equivalent if they are referentially (===) equal.

Setting MutableState.value to its current referentially (===) equal value is not considered a change. When applying a MutableSnapshot, if the snapshot changes the value to the equivalent value the parent snapshot has is not considered a conflict.

@Composable
inline fun <T : Any?> remember(crossinline calculation: @DisallowComposableCalls () -> T): T

Remember the value produced by calculation. calculation will only be evaluated during the composition. Recomposition will always return the value produced by composition.

@Composable
inline fun <T : Any?> remember(
    key1: Any?,
    crossinline calculation: @DisallowComposableCalls () -> T
): T

Remember the value returned by calculation if key1 compares equal (==) to the value it had in the previous composition, otherwise produce and remember a new value by calling calculation.

@Composable
inline fun <T : Any?> remember(
    vararg keys: Any?,
    crossinline calculation: @DisallowComposableCalls () -> T
): T

Remember the value returned by calculation if all values of keys are equal (==) to the values they had in the previous composition, otherwise produce and remember a new value by calling calculation.

@Composable
inline fun <T : Any?> remember(
    key1: Any?,
    key2: Any?,
    crossinline calculation: @DisallowComposableCalls () -> T
): T

Remember the value returned by calculation if key1 and key2 are equal (==) to the values they had in the previous composition, otherwise produce and remember a new value by calling calculation.

@Composable
inline fun <T : Any?> remember(
    key1: Any?,
    key2: Any?,
    key3: Any?,
    crossinline calculation: @DisallowComposableCalls () -> T
): T

Remember the value returned by calculation if key1, key2 and key3 are equal (==) to values they had in the previous composition, otherwise produce and remember a new value by calling calculation.

@Composable
fun rememberCompositionContext(): CompositionContext

An Effect to construct a CompositionContext at the current point of composition. This can be used to run a separate composition in the context of the current one, preserving CompositionLocals and propagating invalidations. When this call leaves the composition, the context is invalidated.

@Composable
inline fun rememberCoroutineScope(
    crossinline getContext: @DisallowComposableCalls () -> CoroutineContext = {
        EmptyCoroutineContext
    }
): CoroutineScope

Return a CoroutineScope bound to this point in the composition using the optional CoroutineContext provided by getContext. getContext will only be called once and the same CoroutineScope instance will be returned across recompositions.