Android 12 Developer Preview is here! Try it out, and give us your feedback!

Modifier

@Stable interface Modifier
androidx.compose.ui.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.

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.padding
import androidx.compose.material.Text

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
)
Modifier implementations should offer a fluent factory extension function on Modifier forcreating combined modifiers by starting from existing modifiers:
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.padding

class FancyModifier(val level: Float) : Modifier.Element

fun Modifier.fancy(level: Float) = this.then(FancyModifier(level))

Row(Modifier.fancy(1f).padding(10.dp)) {
    // content
}

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:

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.padding

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

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:

import androidx.compose.foundation.layout.Row
import androidx.compose.material.Button
import androidx.compose.material.Text

@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")
        }
    }
}

Summary

Nested classes
companion

The companion object Modifier is the empty, default, or starter Modifier that contains no elements.

abstract

A single element contained within a Modifier chain.

Public methods
abstract Boolean
all(predicate: (Modifier.Element) -> Boolean)

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

abstract Boolean
any(predicate: (Modifier.Element) -> Boolean)

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

abstract R
foldIn(initial: R, operation: (R, Modifier.Element) -> R)

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

abstract R
foldOut(initial: R, operation: (Modifier.Element, R) -> R)

Accumulates a value starting with initial and applying op