Split button

Pairs a primary action with a menu of related alternatives.

Category: Actions
API status: Expressive
Compose APIs: SplitButtonLayout, SplitButtonDefaults.LeadingButton, SplitButtonDefaults.TrailingButton
Interactive page: https://m3e.ljzapps.app/#components/split-button

When to use

A split button has two touch targets: the leading button runs the main action and the trailing button opens a menu. The trailing button toggles, and its shape and arrow reflect whether the menu is open.

Compose the pieces with SplitButtonLayout and the buttons from SplitButtonDefaults. Pick the shapes, padding and icon sizes for the height with the ...For(height) helpers.

Playground

The interactive page has a playground with live property controls for this component and generated code.

Examples

Menu on the trailing button

The arrow rotates while the menu is open.

var expanded by remember { mutableStateOf(false) }

SplitButtonLayout(
    leadingButton = {
        SplitButtonDefaults.LeadingButton(onClick = {}) {
            Icon(
                Icons.Rounded.Edit,
                contentDescription = null,
                modifier = Modifier.size(SplitButtonDefaults.LeadingIconSize),
            )
            Spacer(Modifier.width(ButtonDefaults.IconSpacing))
            Text("Edit")
        }
    },
    trailingButton = {
        SplitButtonDefaults.TrailingButton(
            checked = expanded,
            onCheckedChange = { expanded = it },
            modifier = Modifier.semantics { contentDescription = "More options" },
        ) {
            val rotation by animateFloatAsState(if (expanded) 180f else 0f)
            Icon(
                Icons.Rounded.KeyboardArrowDown,
                contentDescription = null,
                modifier = Modifier.size(SplitButtonDefaults.TrailingIconSize).rotate(rotation),
            )
        }
        DropdownMenu(expanded = expanded, onDismissRequest = { expanded = false }) {
            DropdownMenuItem(text = { Text("Edit as copy") }, onClick = { expanded = false })
            DropdownMenuItem(text = { Text("Rename") }, onClick = { expanded = false })
        }
    },
)

Parameters

Name	Type	Default	Description
`leadingButton`	`@Composable () -> Unit`		The primary action.
`trailingButton`	`@Composable () -> Unit`		The toggle that opens the menu.
`spacing`	`Dp`	`SplitButtonDefaults.Spacing`	Gap between the two buttons.

Guidelines

Do:

Make the leading action the most common one.
Keep the menu short.

Don't:

Do not hide the primary action in the menu.
Do not use it when there is only one action.

Accessibility

Give the trailing button a content description such as More options, because it only shows an arrow.
The trailing button exposes its expanded state. Return focus to it when the menu closes.