SwipeAway Gesture

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.

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.

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.

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:

  1. onDown
  2. onMove
  3. onCancel (swipe gesture identified)
  4. onSwipeMove (repeatedly as the swipe position changes)
  5. 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!"
      }
    }
  ]
}