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

ComposablesKt

public final class ComposablesKt


Summary

Public methods

static final void
@Composable
<T extends Object, E extends Applier<@NonNull ?>> ComposeNode(
    @NonNull Function0<@NonNull T> factory,
    @DisallowComposableCalls @ExtensionFunctionType @NonNull Function1<@NonNull Updater<@NonNull T>, Unit> update
)

Emits a node into the composition of type T.

static final void
@Composable
<T extends Object, E extends Applier<@NonNull ?>> ComposeNode(
    @NonNull Function0<@NonNull T> factory,
    @DisallowComposableCalls @ExtensionFunctionType @NonNull Function1<@NonNull Updater<@NonNull T>, Unit> update,
    @Composable @NonNull Function0<Unit> content
)

Emits a node into the composition of type T.

static final void
@Composable
@ExplicitGroupsComposable
<T extends Object, E extends Applier<@NonNull ?>> ComposeNode(
    @NonNull Function0<@NonNull T> factory,
    @DisallowComposableCalls @ExtensionFunctionType @NonNull Function1<@NonNull Updater<@NonNull T>, Unit> update,
    @Composable @ExtensionFunctionType @NonNull Function1<@NonNull SkippableUpdater<@NonNull T>, Unit> skippableUpdate,
    @Composable @NonNull Function0<Unit> content
)

Emits a node into the composition of type T.

static final void
@Composable
<T extends Object, E extends Applier<@NonNull ?>> ReusableComposeNode(
    @NonNull Function0<@NonNull T> factory,
    @DisallowComposableCalls @ExtensionFunctionType @NonNull Function1<@NonNull Updater<@NonNull T>, Unit> update
)

Emits a recyclable node into the composition of type T.

static final void
@Composable
<T extends Object, E extends Applier<@NonNull ?>> ReusableComposeNode(
    @NonNull Function0<@NonNull T> factory,
    @DisallowComposableCalls @ExtensionFunctionType @NonNull Function1<@NonNull Updater<@NonNull T>, Unit> update,
    @Composable @NonNull Function0<Unit> content
)

Emits a recyclable node into the composition of type T.

static final void
@Composable
@ExplicitGroupsComposable
<T extends Object, E extends Applier<@NonNull ?>> ReusableComposeNode(
    @NonNull Function0<@NonNull T> factory,
    @DisallowComposableCalls @ExtensionFunctionType @NonNull Function1<@NonNull Updater<@NonNull T>, Unit> update,
    @Composable @ExtensionFunctionType @NonNull Function1<@NonNull SkippableUpdater<@NonNull T>, Unit> skippableUpdate,
    @Composable @NonNull Function0<Unit> content
)

Emits a recyclable node into the composition of type T.

static final void
@Composable
ReusableContent(Object key, @Composable @NonNull Function0<Unit> content)

A utility function to mark a composition as supporting recycling.

static final void
@Composable
@ExplicitGroupsComposable
ReusableContentHost(
    boolean active,
    @Composable @NonNull Function0<Unit> content
)

An optional utility function used when hosting ReusableContent.

static final @NonNull Composer

TODO(lmr): provide documentation

static final int

This a hash value used to coordinate map externally stored state to the composition.

static final @NonNull CompositionLocalContext

Returns the current CompositionLocalContext which contains all CompositionLocal's in the current composition and their values provided by CompositionLocalProvider's.

static final @NonNull RecomposeScope

Returns an object which can be used to invalidate the current scope at this point in composition.

static final @NonNull T
@Composable
<T extends Object> key(
    Object keys,
    @Composable @NonNull Function0<@NonNull T> block
)

key is a utility composable that is used to "group" or "key" a block of execution inside of a composition.

static final @NonNull T
@Composable
<T extends Object> remember(
    @DisallowComposableCalls @NonNull Function0<@NonNull T> calculation
)

Remember the value produced by calculation.

static final @NonNull T
@Composable
<T extends Object> remember(
    Object key1,
    @DisallowComposableCalls @NonNull Function0<@NonNull T> calculation
)

Remember the value returned by calculation if key1 is equal to the previous composition, otherwise produce and remember a new value by calling calculation.

static final @NonNull T
@Composable
<T extends Object> remember(
    Object keys,
    @DisallowComposableCalls @NonNull Function0<@NonNull T> calculation
)

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

static final @NonNull T
@Composable
<T extends Object> remember(
    Object key1,
    Object key2,
    @DisallowComposableCalls @NonNull Function0<@NonNull T> calculation
)

Remember the value returned by calculation if key1 and key2 are equal to the previous composition, otherwise produce and remember a new value by calling calculation.

static final @NonNull T
@Composable
<T extends Object> remember(
    Object key1,
    Object key2,
    Object key3,
    @DisallowComposableCalls @NonNull Function0<@NonNull T> calculation
)

Remember the value returned by calculation if key1, key2 and key3 are equal to the previous composition, otherwise produce and remember a new value by calling calculation.

static final @NonNull CompositionContext

An Effect to construct a CompositionContext at the current point of composition.

Public methods

ComposeNode

@Composable
public static final void <T extends Object, E extends Applier<@NonNull ?>> ComposeNode(
    @NonNull Function0<@NonNull T> factory,
    @DisallowComposableCalls @ExtensionFunctionType @NonNull Function1<@NonNull Updater<@NonNull T>, Unit> update
)

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.Composition
import androidx.compose.runtime.CompositionContext
import androidx.compose.runtime.ComposeNode
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++ }
        }
    }
}
Parameters
@NonNull Function0<@NonNull T> factory

A function which will create a new instance of T. This function is NOT guaranteed to be called in place.

@DisallowComposableCalls @ExtensionFunctionType @NonNull Function1<@NonNull Updater<@NonNull T>, Unit> update

A function to perform updates on the node. This will run every time emit is executed. This function is called in place and will be inlined.

ComposeNode

@Composable
public static final void <T extends Object, E extends Applier<@NonNull ?>> ComposeNode(
    @NonNull Function0<@NonNull T> factory,
    @DisallowComposableCalls @ExtensionFunctionType @NonNull Function1<@NonNull Updater<@NonNull T>, Unit> update,
    @Composable @NonNull Function0<Unit> content
)

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.Composition
import androidx.compose.runtime.CompositionContext
import androidx.compose.runtime.ComposeNode
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++ }
        }
    }
}
Parameters
@NonNull Function0<@NonNull T> factory

A function which will create a new instance of T. This function is NOT guaranteed to be called in place.

@DisallowComposableCalls @ExtensionFunctionType @NonNull Function1<@NonNull Updater<@NonNull T>, Unit> update

A function to perform updates on the node. This will run every time emit is executed. This function is called in place and will be inlined.

@Composable @NonNull Function0<Unit> content

the composable content that will emit the "children" of this node.

ComposeNode

@Composable
@ExplicitGroupsComposable
public static final void <T extends Object, E extends Applier<@NonNull ?>> ComposeNode(
    @NonNull Function0<@NonNull T> factory,
    @DisallowComposableCalls @ExtensionFunctionType @NonNull Function1<@NonNull Updater<@NonNull T>, Unit> update,
    @Composable @ExtensionFunctionType @NonNull Function1<@NonNull SkippableUpdater<@NonNull T>, Unit> skippableUpdate,
    @Composable @NonNull Function0<Unit> content
)

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.Composition
import androidx.compose.runtime.CompositionContext
import androidx.compose.runtime.ComposeNode
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++ }
        }
    }
}
Parameters
@NonNull Function0<@NonNull T> factory

A function which will create a new instance of T. This function is NOT guaranteed to be called in place.

@DisallowComposableCalls @ExtensionFunctionType @NonNull Function1<@NonNull Updater<@NonNull T>, Unit> update

A function to perform updates on the node. This will run every time emit is executed. This function is called in place and will be inlined.

@Composable @ExtensionFunctionType @NonNull Function1<@NonNull SkippableUpdater<@NonNull T>, Unit> skippableUpdate

A function to perform updates on the node. Unlike update, this function is Composable and will therefore be skipped unless it has been invalidated by some other mechanism. This can be useful to perform expensive calculations for updating the node where the calculations are likely to have the same inputs over time, so the function's execution can be skipped.

@Composable @NonNull Function0<Unit> content

the composable content that will emit the "children" of this node.

ReusableComposeNode

@Composable
public static final void <T extends Object, E extends Applier<@NonNull ?>> ReusableComposeNode(
    @NonNull Function0<@NonNull T> factory,
    @DisallowComposableCalls @ExtensionFunctionType @NonNull Function1<@NonNull Updater<@NonNull T>, Unit> update
)

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.Composition
import androidx.compose.runtime.CompositionContext
import androidx.compose.runtime.ComposeNode
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++ }
        }
    }
}
Parameters
@NonNull Function0<@NonNull T> factory

A function which will create a new instance of T. This function is NOT guaranteed to be called in place.

@DisallowComposableCalls @ExtensionFunctionType @NonNull Function1<@NonNull Updater<@NonNull T>, Unit> update

A function to perform updates on the node. This will run every time emit is executed. This function is called in place and will be inlined.

ReusableComposeNode

@Composable
public static final void <T extends Object, E extends Applier<@NonNull ?>> ReusableComposeNode(
    @NonNull Function0<@NonNull T> factory,
    @DisallowComposableCalls @ExtensionFunctionType @NonNull Function1<@NonNull Updater<@NonNull T>, Unit> update,
    @Composable @NonNull Function0<Unit> content
)

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.Composition
import androidx.compose.runtime.CompositionContext
import androidx.compose.runtime.ComposeNode
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++ }
        }
    }
}
Parameters
@NonNull Function0<@NonNull T> factory

A function which will create a new instance of T. This function is NOT guaranteed to be called in place.

@DisallowComposableCalls @ExtensionFunctionType @NonNull Function1<@NonNull Updater<@NonNull T>, Unit> update

A function to perform updates on the node. This will run every time emit is executed. This function is called in place and will be inlined.

@Composable @NonNull Function0<Unit> content

the composable content that will emit the "children" of this node.

ReusableComposeNode

@Composable
@ExplicitGroupsComposable
public static final void <T extends Object, E extends Applier<@NonNull ?>> ReusableComposeNode(
    @NonNull Function0<@NonNull T> factory,
    @DisallowComposableCalls @ExtensionFunctionType @NonNull Function1<@NonNull Updater<@NonNull T>, Unit> update,
    @Composable @ExtensionFunctionType @NonNull Function1<@NonNull SkippableUpdater<@NonNull T>, Unit> skippableUpdate,
    @Composable @NonNull Function0<Unit> content
)

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.Composition
import androidx.compose.runtime.CompositionContext
import androidx.compose.runtime.ComposeNode
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++ }
        }
    }
}
Parameters
@NonNull Function0<@NonNull T> factory

A function which will create a new instance of T. This function is NOT guaranteed to be called in place.

@DisallowComposableCalls @ExtensionFunctionType @NonNull Function1<@NonNull Updater<@NonNull T>, Unit> update

A function to perform updates on the node. This will run every time emit is executed. This function is called in place and will be inlined.

@Composable @ExtensionFunctionType @NonNull Function1<@NonNull SkippableUpdater<@NonNull T>, Unit> skippableUpdate

A function to perform updates on the node. Unlike update, this function is Composable and will therefore be skipped unless it has been invalidated by some other mechanism. This can be useful to perform expensive calculations for updating the node where the calculations are likely to have the same inputs over time, so the function's execution can be skipped.

@Composable @NonNull Function0<Unit> content

the composable content that will emit the "children" of this node.

ReusableContent

@Composable
public static final void ReusableContent(Object key, @Composable @NonNull Function0<Unit> content)

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.

Parameters
Object key

the value that is used to trigger recycling. If recomposed with a different value the composer creates a new composition but tries to reuse reusable nodes.

@Composable @NonNull Function0<Unit> content

the composable children that are recyclable.

ReusableContentHost

@Composable
@ExplicitGroupsComposable
public static final void ReusableContentHost(
    boolean active,
    @Composable @NonNull Function0<Unit> content
)

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.

Parameters
boolean active

when active is true content is composed normally. When active is false then the content is deactivated and all remembered state is treated as if the content was deleted but the nodes managed by the composition's Applier are unaffected. A active becomes true any reusable nodes from the previously active composition are candidates for reuse.

@Composable @NonNull Function0<Unit> content

the composable content that is managed by this composable.

getCurrentComposer

@Composable
public static final @NonNull Composer getCurrentComposer()

TODO(lmr): provide documentation

getCurrentCompositeKeyHash

@Composable
@ExplicitGroupsComposable
public static final int getCurrentCompositeKeyHash()

This a hash value used to coordinate map externally stored state to the composition. For example, this is used by saved instance state to preserve state across activity lifetime boundaries.

This value is likely to be unique but is not guaranteed unique. There are known cases, such as for loops without a key, where the runtime does not have enough information to make the compound key hash unique.

getCurrentCompositionLocalContext

@Composable
public static final @NonNull CompositionLocalContext getCurrentCompositionLocalContext()

Returns the current CompositionLocalContext which contains all CompositionLocal's in the current composition and their values provided by CompositionLocalProvider's. This context can be used to pass locals to another composition via CompositionLocalProvider. That is usually needed if another composition is not a subcomposition of the current one.

getCurrentRecomposeScope

@Composable
public static final @NonNull RecomposeScope getCurrentRecomposeScope()

Returns an object which can be used to invalidate the current scope at this point in composition. This object can be used to manually cause recompositions.

key

@Composable
public static final @NonNull T <T extends Object> key(
    Object keys,
    @Composable @NonNull Function0<@NonNull T> block
)

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)
}
Parameters
Object keys

The set of values to be used to create a compound key. These will be compared to their previous values using equals and hashCode

@Composable @NonNull Function0<@NonNull T> block

The composable children for this group.

remember

@Composable
public static final @NonNull T <T extends Object> remember(
    @DisallowComposableCalls @NonNull Function0<@NonNull T> calculation
)

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

remember

@Composable
public static final @NonNull T <T extends Object> remember(
    Object key1,
    @DisallowComposableCalls @NonNull Function0<@NonNull T> calculation
)

Remember the value returned by calculation if key1 is equal to the previous composition, otherwise produce and remember a new value by calling calculation.

remember

@Composable
public static final @NonNull T <T extends Object> remember(
    Object keys,
    @DisallowComposableCalls @NonNull Function0<@NonNull T> calculation
)

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

remember

@Composable
public static final @NonNull T <T extends Object> remember(
    Object key1,
    Object key2,
    @DisallowComposableCalls @NonNull Function0<@NonNull T> calculation
)

Remember the value returned by calculation if key1 and key2 are equal to the previous composition, otherwise produce and remember a new value by calling calculation.

remember

@Composable
public static final @NonNull T <T extends Object> remember(
    Object key1,
    Object key2,
    Object key3,
    @DisallowComposableCalls @NonNull Function0<@NonNull T> calculation
)

Remember the value returned by calculation if key1, key2 and key3 are equal to the previous composition, otherwise produce and remember a new value by calling calculation.

rememberCompositionContext

@Composable
public static final @NonNull CompositionContext rememberCompositionContext()

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.