SwipeToReveal

Component in Wear Material 3 Compose

[SwipeToReveal] Material composable. This adds the option to configure up to two additional actions on a Composable: a mandatory [SwipeToRevealScope.primaryAction] and an optional [SwipeToRevealScope.secondaryAction]. These actions are initially hidden and revealed only when the [content] is swiped. These additional actions can be triggered by clicking on them after they are revealed. [SwipeToRevealScope.primaryAction] will be triggered on full swipe of the [content].

For actions like "Delete", consider adding [SwipeToRevealScope.undoPrimaryAction] (displayed when the [SwipeToRevealScope.primaryAction] is activated). Adding undo composables allow users to undo the action that they just performed.

[SwipeToReveal] composable adds the [CustomAccessibilityAction]s using the labels from primary and secondary actions.

Example of [SwipeToReveal] with primary and secondary actions

Last updated: 2024-10-22 13:47

Installation

dependencies {
   implementation("androidx.wear.compose:compose-material3:1.0.0-alpha27")
}

Overloads

@Composable
fun SwipeToReveal(
    actions: SwipeToRevealScope.() -> Unit,
    modifier: Modifier = Modifier,
    revealState: RevealState = rememberRevealState(),
    actionButtonHeight: Dp = SwipeToRevealDefaults.SmallActionButtonHeight,
    content: @Composable () -> Unit,
)

Parameters

name	description
actions	Actions of the [SwipeToReveal] composable, such as [SwipeToRevealScope.primaryAction]. [actions] should always include exactly one [SwipeToRevealScope.primaryAction]. [SwipeToRevealScope.secondaryAction], [SwipeToRevealScope.undoPrimaryAction] and [SwipeToRevealScope.undoSecondaryAction] are optional.
modifier	[Modifier] to be applied on the composable
revealState	[RevealState] of the [SwipeToReveal]
actionButtonHeight	Desired height of the revealed action buttons. In case the content is a Button composable, it's suggested to use [SwipeToRevealDefaults.SmallActionButtonHeight], and for a Card composable, it's suggested to use [SwipeToRevealDefaults.LargeActionButtonHeight].
content	The content that will be initially displayed over the other actions provided.

Code Examples

SwipeToRevealSample

@Composable
fun SwipeToRevealSample() {
    SwipeToReveal(
        // Use the double action anchor width when revealing two actions
        revealState =
            rememberRevealState(
                anchorWidth = SwipeToRevealDefaults.DoubleActionAnchorWidth,
            ),
        actions = {
            primaryAction(
                onClick = { /* This block is called when the primary action is executed. */ },
                icon = { Icon(Icons.Outlined.Delete, contentDescription = "Delete") },
                label = "Delete"
            )
            secondaryAction(
                onClick = { /* This block is called when the secondary action is executed. */ },
                icon = { Icon(Icons.Outlined.MoreVert, contentDescription = "Options") },
                label = "Options"
            )
            undoPrimaryAction(
                onClick = { /* This block is called when the undo primary action is executed. */ },
                label = "Undo Delete"
            )
        }
    ) {
        Button(modifier = Modifier.fillMaxWidth(), onClick = {}) {
            Text("This Button has two actions", modifier = Modifier.fillMaxSize())
        }
    }
}

SwipeToRevealSingleActionCardSample

@Composable
fun SwipeToRevealSingleActionCardSample() {
    SwipeToReveal(
        actionButtonHeight = SwipeToRevealDefaults.LargeActionButtonHeight,
        actions = {
            primaryAction(
                onClick = { /* This block is called when the primary action is executed. */ },
                icon = { Icon(Icons.Outlined.Delete, contentDescription = "Delete") },
                label = "Delete"
            )
        }
    ) {
        Card(modifier = Modifier.fillMaxWidth(), onClick = {}) {
            Text(
                "This Card has one action, and the revealed button is taller",
                modifier = Modifier.fillMaxSize()
            )
        }
    }
}

SwipeToRevealNonAnchoredSample

@Composable
fun SwipeToRevealNonAnchoredSample() {
    SwipeToReveal(
        revealState = rememberRevealState(useAnchoredActions = false),
        actions = {
            primaryAction(
                onClick = { /* This block is called when the primary action is executed. */ },
                icon = { Icon(Icons.Outlined.Delete, contentDescription = "Delete") },
                label = "Delete"
            )
            undoPrimaryAction(
                onClick = { /* This block is called when the undo primary action is executed. */ },
                icon = { Icon(Icons.Outlined.Refresh, contentDescription = "Undo") },
                label = "Undo"
            )
        }
    ) {
        Button(modifier = Modifier.fillMaxWidth(), onClick = {}) {
            Text("Swipe to execute the primary action.", modifier = Modifier.fillMaxSize())
        }
    }
}