compose-slot-api-pattern

Compose: slot API pattern

Core principle

A reusable Compose component describes layout structure. Callers provide variable visual content through slots.

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

Where the component asks for caller-controlled content, prefer a @Composable () -> Unit slot. Where the slot is structurally required, leave it non-nullable with no default. Where it's optional, make it nullable with a null default.

// ❌ 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,
) { … }

Call sites stay short when the typical content is a one-liner:

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