SwipeAway Gesture

Note: Learn how to improve your skills with APL with Build visually rich experiences using APL at the Alexa Learning Lab.

Important: SwipeAway gesture requires APL 1.4 or later. Provide an alternate experience for devices running older versions of APL.

The SwipeAway gesture provides support for swiping across a touchable component to reveal a different component. The user triggers a SwipeAway by swiping the component in a specified direction. Use SwipeAway to create a "swipe to delete" interaction.

Note: You can use SwipeAway with the TouchWrapper component. Other touchable components don't support SwipeAway.

Properties

The gesture includes the following properties:

Property	Type	Default	Description
`type`	"SwipeAway"	REQUIRED	Must be "SwipeAway".
`action`	string	`slide`	Specifies how to display the original and child components during the swipe gesture. One of `reveal` \| `slide` \| `cover`.
`direction`	string	REQUIRED	Direction the user swipes to activate the gesture. One of `left` \| `right` \| `up` \| `down` \| `forward` \| `backward`.
`item`, `items`	Array of components and layouts	[]	A new item to display during and after the swipe gesture. This item replaces the original item.
`onSwipeMove`	Array of Commands	[]	Commands to run as the swipe position changes.
`onSwipeDone`	Array of Commands	[]	Commands to run when the swipe is complete.

action

The action property controls how the original component exits the viewport and how the new component enters the screen. The action property can take the following values:

Type	Original component	Child component
cover	Remains in a fixed position	Slides in on top of the original component and covers the original component.
reveal	Slides out	Appears in a fixed position behind the original, fully revealed as the original component slides away.
slide	Slides out	Slides in. The leading edge of the child component attaches to trailing edge of original.

The cover and reveal swipe actions don't set clipping regions. When the overlaying component has a transparent background, the underlying component is visible.

direction

The direction the user swipes to trigger the swipe gesture. The direction property can take the following values:

Type	Description
down	Swipe from the top of the component towards the bottom
left	Swipe from the right side of the component towards the left
right	Swipe from the left side of the component towards the right
up	Swipe from the bottom of the component towards the top
forward	Swipe in a forward direction as determined by the `layoutDirection` property set on the component.
backward	Swipe in a backward direction as determined by the `layoutDirection` property set on the component

The forward and backward values depend on the value of the layoutDirection property on the component.

Property value	Left-to-right ("LTR")	Right-to-left ("RTL")
`forward`	Equivalent to `right`. The user swipes from the left towards the right.	Equivalent to `left`. The user swipes from the right towards the left.
`backward`	Equivalent to `left`. The user swipes from the right towards the left.	Equivalent to `right`. The user swipes from the left towards the right.

items

The child component or layout to replace the original component. If items contains an array of multiple items, the first one selected by the when property (Single child inflation) is used.

The child component size and position use the same size and position of the original component. When you don't provide a child component in items, the swipe still occurs. However, if the swipe action is cover, the user doesn't see the effect of the swipe until the swipe completes.

onSwipeMove

Commands to run as the swipe position moves. This command runs every time the position of the swipe changes. The event generated has the following form.

"event": {
  "source": {
    "type": "COMPONENT_TYPE", // The type of the component
    "handler": "SwipeMove",
    ...                     // Component source properties
  },
  "position": NUMBER,   // A number between 0 and 1 representing the percentage of the swipe distance
  "direction": "STRING"   // One of "left", "right", "up" or "down" matching the swipe direction
}

The position property is a number between 0 and 1 representing the current swipe distance. The value 0 corresponds to no swipe (only the original component is visible) and the value 1 corresponds to full swipe (only the child component is visible).

The direction property is the direction property defined in the gesture.

Refer to Event source for a description of event.source properties.

The onSwipeMove handler runs in fast mode in the component data-binding context.

onSwipeDone

Commands to run when the swipe gesture completes. This command runs if the swipe gesture completes. The commands don't run when the user stops the swipe and leaves the original component visible. The event generated has following form.

"event": {
  "source": {
    "type": "COMPONENT_TYPE", // The type of the component
    "handler": "SwipeDone",
    ...                     // Component source properties
  },
  "direction": "STRING"   // One of "left", "right", "up" or "down" matching the swipe direction
}

The direction property is the direction property defined in the gesture.

Refer to Event source for a description of event.source properties.

The onSwipeDone handler runs in normal mode in the component data-binding context.

Event sequence for the SwipeAway gesture

When a user begins a SwipeAway gesture, the component with the SwipeAway gesture moves out with the swipe and a new component defined by the items property moves into view. The swipe gesture limits the movement of the component to the component width for left/right gestures and the component height for up/down gestures.

A SwipeAway event triggers the following handlers:

onDown
onMove
onCancel (swipe gesture identified)
onSwipeMove (repeatedly as the swipe position changes)
onSwipeDone (after the user has finished swiping and the animation completes)

The SwipeAway gesture occurs when the user taps the component and drags it in the swipe direction (direction).

The SwipeAway gesture supports "flinging." This means that the user isn't required to swipe across the entire component to complete the gesture. Instead, the gesture animates to completion in two scenarios:

The user releases the component after dragging past the 50 percent point.
The user swipes the component with enough momentum such that the gesture passes the 50 percent point.

When the swipe doesn't complete, the component animates returning to the original component.

Fully completing the swipe removes the original component. The child component displays in its place. You can't return a fully-swiped component to the starting state.

Child component selection

When the swipe gesture starts, the first item in the items child array where when is true inflates according to the Single child inflation rule. The position and size of the child item updates to match dimensions and position of the original touchable component. During the swipe motion, the transform of the original component and the child component update so that the trailing side of the original component and the leading side of the child component match the current swipe position. This results in an effect in which the entering child component is attached to the trailing edge of the departing component.

Example swipe-to-delete

The following example illustrates a "swipe-to-delete" gesture handler that positions a check on the right or left depending on the swipe position.

{
  "type": "TouchWrapper",
  "item": {
    "type": "Text",
    "text": "Lorem ipsum dolor",
    "fontSize": "50"
  },
  "gestures": [
    {
      "type": "SwipeAway",
      "direction": "left",
      "items": {
        "type": "Frame",
        "backgroundColor": "purple",
        "items": {
          "componentId": "MyCheck",
          "type": "Text",
          "text": "✓",
          "fontSize": 60,
          "color": "white",
          "width": 60,
          "height": "100%",
          "textAlign": "center",
          "textVerticalAlign": "center"
        }
      },
      "onSwipeMove": {
        "type": "SetValue",
        "componentId": "MyCheck",
        "property": "transformX",
        "value": "${event.position * event.source.width < event.target.width || event.position > 0.5 ? 0 : event.position * event.source.width - event.target.width}"
      },
      "onSwipeDone": {
        "type": "SendEvent",
        "arguments": "The item was swiped away!"
      }
    }
  ]
}

SwipeAway example

The following example demonstrates the SwipeAway gesture. Each touchable component handler runs a command that displays the ID of the component and the name of the handler that ran. When you do a swipe motion, the onSwipeMove handler runs, followed by onSwipeDone when you finish the swipe. After a completed swipe, the original component with the SwipeAway gesture is gone and replace with a Text component.

Was this page helpful?

Provide feedback

Last updated: Feb 29, 2024