Modifier

@JvmDefaultWithCompatibility
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

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.

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.

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

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

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.

infix fun then(other: Modifier): Modifier

Concatenates this modifier with another.

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

Code Examples

ModifierUsageSample

@Composable
fun ModifierUsageSample() {
    Text(
        "Hello, World!",
        Modifier.padding(16.dp) // Outer padding; outside background
            .background(color = Color.Green) // Solid element background color
            .padding(16.dp), // Inner padding; inside background, around text
    )
}

ModifierFactorySample

@Composable
fun ModifierFactorySample() {
    class FancyModifier(val level: Float) : Modifier.Element
    fun Modifier.fancy(level: Float) = this.then(FancyModifier(level))
    Row(Modifier.fancy(1f).padding(10.dp)) {
        // content
    }
}

ModifierParameterSample

@Composable
fun ModifierParameterSample() {
    @Composable
    fun PaddedColumn(modifier: Modifier = Modifier) {
        Column(modifier.padding(10.dp)) {
            // ...
        }
    }
}

SubcomponentModifierSample

@Composable
fun SubcomponentModifierSample() {
    @Composable
    fun ButtonBar(
        onOk: () -> Unit,
        onCancel: () -> Unit,
        modifier: Modifier = Modifier,
        buttonModifier: Modifier = Modifier,
    ) {
        Row(modifier) {
            Button(onCancel, buttonModifier) { Text("Cancel") }
            Button(onOk, buttonModifier) { Text("Ok") }
        }
    }
}