Modifier

public interface Modifier

An ordered, immutable collection of modifier elements that decorate or add behavior to Compose UI elements. For example, backgrounds, padding and click event listeners decorate or add behavior to rows, text or buttons.

Modifier implementations should offer a fluent factory extension function on Modifier for creating combined modifiers by starting from existing modifiers:

Modifier elements may be combined using then. Order is significant; modifier elements that appear first will be applied first.

Composables that accept a Modifier as a parameter to be applied to the whole component represented by the composable function should name the parameter modifier and assign the parameter a default value of Modifier. It should appear as the first optional parameter in the parameter list; after all required parameters (except for trailing lambda parameters) but before any other parameters with default values. Any default modifiers desired by a composable function should come after the modifier parameter's value in the composable function's implementation, keeping Modifier as the default parameter value. For example:

The pattern above allows default modifiers to still be applied as part of the chain if a caller also supplies unrelated modifiers.

Composables that accept modifiers to be applied to a specific subcomponent foo should name the parameter fooModifier and follow the same guidelines above for default values and behavior. Subcomponent modifiers should be grouped together and follow the parent composable's modifier. For example:

Functions

foldIn

public fun <R> foldIn(initial: R, operation: (R, Element) -> R): R

Accumulates a value starting with initial and applying operation to the current value and each element from outside in.

Elements wrap one another in a chain from left to right; an Element that appears to the left of another in a + expression or in operation's parameter order affects all of the elements that appear after it. foldIn may be used to accumulate a value starting from the parent or head of the modifier chain to the final wrapped child.

foldOut

public fun <R> foldOut(initial: R, operation: (Element, R) -> R): R

Accumulates a value starting with initial and applying operation to the current value and each element from inside out.

Elements wrap one another in a chain from left to right; an Element that appears to the left of another in a + expression or in operation's parameter order affects all of the elements that appear after it. foldOut may be used to accumulate a value starting from the child or tail of the modifier chain up to the parent or head of the chain.

any

public fun any(predicate: (Element) -> Boolean): Boolean

Returns true if predicate returns true for any Element in this Modifier.

all

public fun all(predicate: (Element) -> Boolean): Boolean

Returns true if predicate returns true for all Elements in this Modifier or if this Modifier contains no Elements.

then

public infix fun then(other: Modifier): Modifier

Concatenates this modifier with another.

Returns a Modifier representing this modifier followed by other in sequence.

Members

Element

public interface Element : Modifier

A single element contained within a Modifier chain.

Node

public abstract class Node : DelegatableNode

The longer-lived object that is created for each Modifier.Element applied to a androidx.compose.ui.layout.Layout. Most Modifier.Node implementations will have a corresponding "Modifier Factory" extension method on Modifier that will allow them to be used indirectly, without ever implementing a Modifier.Node subclass directly. In some cases it may be useful to define a custom Modifier.Node subclass in order to efficiently implement some collection of behaviors that requires maintaining state over time and over many recompositions where the various provided Modifier factories are not sufficient.

When a Modifier is set on a androidx.compose.ui.layout.Layout, each Modifier.Element contained in that linked list will result in a corresponding Modifier.Node instance in a matching linked list of Modifier.Nodes that the androidx.compose.ui.layout.Layout will hold on to. As subsequent Modifier chains get set on the androidx.compose.ui.layout.Layout, the linked list of Modifier.Nodes will be diffed and updated as appropriate, even though the Modifier instance might be completely new. As a result, the lifetime of a Modifier.Node is the intersection of the lifetime of the androidx.compose.ui.layout.Layout that it lives on and a corresponding Modifier.Element being present in the androidx.compose.ui.layout.Layout's Modifier.

If one creates a subclass of Modifier.Node, it is expected that it will implement one or more interfaces that interact with the various Compose UI subsystems. To use the Modifier.Node subclass, it is expected that it will be instantiated by adding a androidx.compose.ui.node.ModifierNodeElement to a Modifier chain.

Properties

node

public final override var node: Node = this

coroutineScope

public val coroutineScope: CoroutineScope

A CoroutineScope that can be used to launch tasks that should run while the node is attached.

The scope is accessible between onAttach and onDetach calls, and will be cancelled after the node is detached (after onDetach returns).

Throws: IllegalStateException

If called while the node is not attached.

isAttached

public var isAttached: Boolean = false

Indicates that the node is attached to a androidx.compose.ui.layout.Layout which is part of the UI tree. This will get set to true right before onAttach is called, and set to false right after onDetach is called.

shouldAutoInvalidate

public open val shouldAutoInvalidate: Boolean

If this property returns true, then nodes will be automatically invalidated after the modifier update completes (For example, if the returned Node is a DrawModifierNode, its androidx.compose.ui.node.invalidateDraw function will be invoked automatically as part of auto invalidation).

This is enabled by default, and provides a convenient mechanism to schedule invalidation and apply changes made to the modifier. You may choose to set this to false if your modifier has auto-invalidatable properties that do not frequently require invalidation to improve performance by skipping unnecessary invalidation. If autoInvalidate is set to false, you must call the appropriate invalidate functions manually when the modifier is updated or else the updates may not be reflected in the UI appropriately.

Functions

onAttach

@EmptySuper public open fun onAttach()

Called when the node is attached to a androidx.compose.ui.layout.Layout which is part of the UI tree. When called, node is guaranteed to be non-null. You can call sideEffect, coroutineScope, etc. This is not guaranteed to get called at a time where the rest of the Modifier.Nodes in the hierarchy are "up to date". For instance, at the time of calling onAttach for this node, another node may be in the tree that will be detached by the time Compose has finished applying changes. As a result, if you need to guarantee that the state of the tree is "final" for this round of changes, you should use the sideEffect API to schedule the calculation to be done at that time.

onDetach

@EmptySuper public open fun onDetach()

Called when the node is not attached to a androidx.compose.ui.layout.Layout which is not a part of the UI tree anymore. Note that the node can be reattached again.

This should be called right before the node gets removed from the list, so you should still be able to traverse inside of this method. Ideally we would not allow you to trigger side effects here.

onReset

@EmptySuper public open fun onReset()

Called when the node is about to be moved to a pool of layouts ready to be reused. For example it happens when the node is part of the item of LazyColumn after this item is scrolled out of the viewport. This means this node could be in future reused for a androidx.compose.ui.layout.Layout displaying a semantically different content when the list will be populating a new item.

Use this callback to reset some local item specific state, like "is my component focused".

This callback is called while the node is attached. Right after this callback the node will be detached and later reattached when reused.

sideEffect

public fun sideEffect(effect: () -> Unit)

This can be called to register effect as a function to be executed after all of the changes to the tree are applied.

This API can only be called if the node isAttached.

Companion

public companion object : Modifier

The companion object Modifier is the empty, default, or starter Modifier that contains no elements. Use it to create a new Modifier using modifier extension factory functions:

or as the default value for Modifier parameters: