compose-modifier-and-layout-style

Compose modifier and layout style

Core principle

A composable that emits layout is a leaf the parent places — the parent decides position, size, alignment, padding. The composable's job is structure (what's inside), not placement (where it goes). Three rules follow:

• Declare a modifier parameter and apply it to the root, so the parent can actually do its job. Hardcoding .fillMaxWidth() on a composable's root takes that decision away from every future caller.
• Construct modifier chains as one fluent expression, not stepwise reassignments. Both compile to the same thing, but the chain reads as intent in one pass.
• Conditional rendering belongs where the condition applies. A layout call whose only content is one if exists solely to hold the condition — push the if outside instead.

These travel together because the same composable usually triggers all three: you declare its parameters (rule 1), the caller constructs a chain to position it (rules 2), and the body has a conditional you might be tempted to wrap (rule 3).

When to use this skill

• You're writing a @Composable fun that calls a layout (Box, Column, Row, LazyColumn, Text, Image, Surface, Card, Layout { … }, anything from compose.foundation.layout or compose.material*) and its signature has no modifier parameter, or has one that isn't applied to the root, or has a hardcoded .fillMaxWidth()/.padding(...) on the root.
• You see var m = Modifier followed by m = m.padding(…), m = m.background(…), etc.
• A modifier = … argument has three or more chained calls on a single line.
• A composable's body is Layout { if (cond) Content() } — one conditional, nothing else.

1. Declare a modifier parameter

For composables that emit layout, prefer a modifier parameter after required parameters and before content/lambda parameters, with a default of Modifier. The name is exactly modifier — not mod, not m, not wrapperModifier.

// ❌ BAD — no modifier param; caller can't position, size, or constrain this
@Composable
fun HomeScreenHeader(title: String, subtitle: String) {
    Column(
        modifier = Modifier
            .fillMaxWidth()
            .padding(horizontal = 16.dp),
        verticalArrangement = Arrangement.spacedBy(4.dp),
    ) {
        Text(title, style = MaterialTheme.typography.headlineLarge)
        Text(subtitle, style = MaterialTheme.typography.bodyMedium)
    }
}