Compose: slot API pattern

Core principle

API review procedure

1. Confirm the component is reusable. For a true single-use composable, do not add slot ceremony.
2. Mark which regions vary by caller: headline, supporting text, leading visual, trailing visual, actions, body.
3. Replace caller-controlled primitive content and shape flags with slots.
4. Add receiver scopes only when the slot is emitted inside a layout whose scope APIs callers should use.
5. Make absent optional regions nullable (null), so the component can omit their containers and spacing.
6. Put repeated default content or tokens in XxxDefaults.
7. Pair this with the modifier rules in compose-modifier-and-layout-style.

1. Replace primitive content with @Composable slots

// ❌ BAD — primitive parameters; trailing area is the only slot; everything else is locked
@Composable
fun SettingsRow(
    title: String,
    onClick: () -> Unit,
    modifier: Modifier = Modifier,
    subtitle: String? = null,
    leadingIcon: ImageVector? = null,
    trailing: (@Composable () -> Unit)? = null,
) { … }

// ✅ GOOD — every visual region is a slot; the row describes structure, not content
@Composable
fun SettingsRow(
    headlineContent: @Composable () -> Unit,
    onClick: () -> Unit,
    modifier: Modifier = Modifier,
    supportingContent: (@Composable () -> Unit)? = null,
    leadingContent: (@Composable () -> Unit)? = null,
    trailingContent: (@Composable () -> Unit)? = null,
) { … }

SettingsRow(
    headlineContent = { Text("Account") },
    leadingContent = { Icon(Icons.Default.Person, contentDescription = null) },
    trailingContent = { SettingsRowDefaults.Chevron() },
    onClick = { … },
)

SettingsRow(
    headlineContent = {
        Row(verticalAlignment = Alignment.CenterVertically) {
            Text("Inbox")
            Spacer(Modifier.width(8.dp))
            Badge { Text("3") }
        }
    },
    onClick = { … },
)

Slot naming

• Use xxxContent for free-form @Composable () -> Unit slots (headlineContent, supportingContent, trailingContent) — matches Material 3.
• Use a singular noun (title, icon, actions) when the slot is semantically constrained and the component name disambiguates (Scaffold(topBar = { … }, bottomBar = { … }, floatingActionButton = { … })).
• Don't use content and other xxxContent slots together — pick one convention per component.

2. Scope receivers when the slot emits into a layout

// ❌ BAD — actions render inside a Row, but callers can't use RowScope.weight()
@Composable
fun MyTopBar(
    title: @Composable () -> Unit,
    actions: @Composable () -> Unit = {},   // ← caller has no Row scope
)

// ✅ GOOD — caller gets RowScope; .weight() and alignment-by works inside
@Composable
fun MyTopBar(
    title: @Composable () -> Unit,
    actions: @Composable RowScope.() -> Unit = {},
)

3. Optional slots — nullable with null default

// ❌ BAD — empty default; "no leading content" is the empty lambda
leadingContent: @Composable () -> Unit = {}

// ✅ GOOD — null means "no slot"; the component can omit space/padding when absent
leadingContent: (@Composable () -> Unit)? = null

4. Defaults live in XxxDefaults

object SettingsRowDefaults {
    @Composable
    fun Chevron() = Icon(
        imageVector = Icons.AutoMirrored.Filled.KeyboardArrowRight,
        contentDescription = null,
    )

    @Composable
    fun TrailingValue(text: String) = Text(
        text = text,
        style = MaterialTheme.typography.bodyMedium,
        color = MaterialTheme.colorScheme.onSurfaceVariant,
    )
}

SettingsRow(
    headlineContent = { Text("Notifications") },
    trailingContent = { SettingsRowDefaults.Chevron() },
    onClick = { … },
)

Quick reference

When NOT to apply

• Single-use components. A composable used in exactly one place, with no plan to reuse, doesn't benefit from slot flexibility — and the slot indirection makes the code harder to read for the one reader. Primitive params + inline content is fine. (As soon as a second call site appears, slot it.)
• Design-system primitives where every caller must look identical. A Heading2(text: String) exists because you want every H2 to look the same; making it headlineContent: @Composable () -> Unit invites callers to break the rule. Keep it primitive. (Conversely: if Heading2 ever needs a badge inline, slot it.)
• Semantic parameters the component intentionally owns. If the component owns typography, iconography, accessibility wording, or product consistency, a primitive parameter may be the constraint you want.
• Constrained-type parameters that genuinely are constrained. A Switch(checked: Boolean, onCheckedChange: ...) doesn't need its checked indicator to be a slot. Booleans-with-callbacks are not "content."
• Performance-critical fast paths (rare in app code; common in framework primitives). A slot is an allocated lambda. In the deepest LazyList item layer, sometimes primitives win. If you're not writing the framework, this doesn't apply.

Red flags during review

Related

• compose-modifier-and-layout-style — the modifier-parameter rule (§1–§3 there) travels with slot APIs. A reusable component takes a modifier parameter and slots its content; the caller owns both placement and what to place.