Drag handle

A grabbable bar between two panes that lets people resize them.

Category: Layout and structure
API status: Expressive
Compose APIs: VerticalDragHandle, VerticalDragHandleDefaults
Interactive page: https://m3e.ljzapps.app/#components/drag-handle

When to use

The vertical drag handle sits between panes of a multi-pane layout. It changes shape while it is pressed or dragged. You attach the drag behavior yourself, or let the adaptive pane scaffold do it.

Examples

Resizable split

Drag the handle.

var listWidth by remember { mutableFloatStateOf(220f) }

Row(Modifier.fillMaxWidth().height(200.dp)) {
    Box(
        Modifier.width(listWidth.dp).fillMaxHeight().background(MaterialTheme.colorScheme.surfaceContainerLow),
        contentAlignment = Alignment.Center,
    ) { Text("List") }

    VerticalDragHandle(
        modifier = Modifier
            .padding(horizontal = 8.dp)
            .draggable(
                orientation = Orientation.Horizontal,
                state = rememberDraggableState { delta -> listWidth = (listWidth + delta).coerceIn(120f, 420f) },
            ),
    )

    Box(Modifier.weight(1f).fillMaxHeight().background(MaterialTheme.colorScheme.surfaceContainerHigh), contentAlignment = Alignment.Center) {
        Text("Detail")
    }
}

Parameters

Name	Type	Default	Description
`modifier`	`Modifier`	`Modifier`	Add Modifier.draggable to give the handle behavior.
`sizes`	`DragHandleSizes`	`VerticalDragHandleDefaults.sizes()`	Resting and pressed size.
`shapes`	`DragHandleShapes`	`VerticalDragHandleDefaults.shapes()`	Resting and pressed shape.
`colors`	`DragHandleColors`	`VerticalDragHandleDefaults.colors()`	Resting, pressed and dragged colors.

Guidelines

Do:

Set sensible minimum and maximum pane sizes.
Use only between panes.

Don't:

Do not use it as a decoration.
Do not hide content when a pane gets too small.

Accessibility

Provide a keyboard way to resize the panes, for example arrow keys on the focused handle.
Keep the touch target at least 48 dp wide with padding.