Swipe to Action (1.2.0 - 1.3.0)

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

(This is not the most recent version of AlexaSwipeToAction. Use the Other Versions option to see the documentation for the most recent version of AlexaSwipeToAction)

The Alexa swipe to action responsive component (AlexaSwipeToAction) displays an item the user can swipe to perform an action. You can use this component in lists such as AlexaTextList to provide swipe actions on the list items. You can control the look of the item and the commands to run when the user swipes the item.

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

The AlexaSwipeToAction uses the SwipeAway gesture.

Import the alexa-layouts package

To use AlexaSwipeToAction, import the alexa-layouts package.

The latest version of the alexa-layouts package is 1.7.0. AlexaSwipeToAction was introduced in version 1.2.0.

AlexaSwipeToAction Parameters

All parameters except type are optional.

Name	Type	Default	Description	Version added/updated
`actionIcon`	String	—	The source for a custom icon to show during the swipe. When `actionIconType` is `AVG`, set this property to the name of the graphic as defined in the `graphics` property or in an imported package. When `actionIconType` is `image`, provide the URL of the image to display.	1.2.0
`actionIconBackground`	Color	—	Color to use for the background color displayed behind the action icon when the user swipes the item.	1.2.0
`actionIconForeground`	Color	—	Color to use for the action icon shown when the user swipes the item.	1.2.0
`actionIconType`	String	—	The type of graphic to use for the custom `actionIcon`. Set to `AVG` or `image`. When set to `image`, provide a URL for the image in `actionIcon`. When set to AVG, define an AVG in the graphics property of your document or use graphics defined in an imported package, and then set `actionIcon` to the name of the graphic.	1.2.0
`button1Command`	Any	—	Command to bind to the first button in the options list. Used only for TV devices.	1.2.0
`button1Text`	String	—	Text for the first button in the options list. Used only for TV devices.	1.2.0
`button2Command`	Any	—	Command to bind to the second button in the options list. Used only for TV devices.	1.2.0
`button2Text`	String	—	Text for the second button in the options list. Used only for TV devices.	1.2.0
`buttonsSpacingRight`	Dimension	`@marginHorizontal`	Right position of options component. Used only for TV devices.	1.2.0
`buttonsSpacingTop`	Dimension	Aligned with the ordinal	Top position of options component. Used only for TV devices.	1.2.0
`customLayoutName`	Any	—	The name of a custom layout to use for the item. When not set, the component uses the `AlexaTextListItem` responsive component determine how to display the item.	1.2.0
`direction`	String	`left`	The direction of the swipe gesture. Set to `left` or `right`.
`emptyRatingGraphic`	Any	`empty`	The graphic to display to represent an 'empty' rating slot (such as an empty star). Used when `ratingSlotMode` is `multiple`. You can provide either a reference to an AVG or the URL of an image. On smaller viewports, the rating doesn't display due to space. For details about how to use the `AlexaRating` properties, see AlexaRating.	1.2.0
`entities`	Array	—	Array of entity data to bind to this component.	1.2.0
`fullRatingGraphic`	Any	`full`	The graphic to display to represent a 'full' rating slot (such as a full star). Used when `ratingSlotMode` is `multiple`. You can provide either a reference to an AVG or the URL of an image. On smaller viewports, the rating doesn't display due to space. For details about how to use the `AlexaRating` properties, see AlexaRating.	1.2.0
`halfRatingGraphic`	Any	`half`	The graphic to display to represent a 'half' rating slot (such as a half star). Used when `ratingSlotMode` is `multiple`. You can provide either a reference to an AVG or the URL of an image. On smaller viewports, the rating doesn't display due to space. For details about how to use the `AlexaRating` properties, see AlexaRating.	1.2.0
`hideDivider`	Boolean	`false`	When `true`, hide the horizontal divider displayed below the item.	1.2.0
`hideHorizontalMargin`	Boolean	`false`	When `true`, hide the default left and right padding.	1.2.0
`hideOrdinal`	Boolean	`false`	When `true`, don't display a number next to the item.	1.2.0
`imageAlignment`	String	`center`	Determines how to position the image within the bounding box. Used when the image is smaller than the bounding box. Options are bottom, bottom-left, bottom-right, center, left, right, top, top-left, top-right. This property works the same as the `imageAlignment` property for the `AlexaImage` responsive component.	1.2.0
`imageBlurredBackground`	Boolean	`false`	When `true`, display a blurred version of the image behind the image. Ignored when `imageScale` is set to `fill` or `best-fill`. This property works the same as the `imageBlurredBackground` property for the `AlexaImage` responsive component.	1.2.0
`imageScale`	String	`best-fit`	Determines how to scale the image to fit within the bounding box. Options are none, fill, best-fit, best-fill, best-fit-down. This property works the same as the `imageScale` property for the `AlexaImage` responsive component.	1.2.0
`imageThumbnailShadow`	Boolean	`true`	When `true`, display a drop shadow behind the image thumbnail.	1.3.0
`imageThumbnailSource`	String	—	URI for an image to display next to the item as a thumbnail.	1.2.0
`onButtonsHidden`	Any	—	Command to run when the options list is hidden. Used only for TV devices.	1.2.0
`onButtonsShown`	Any	—	Command to run when the options list is shown. Used only for TV devices.	1.2.0
`onSwipeDone`	Any	—	Command to run when the user completes the swipe action.	1.2.0
`onSwipeMove`	Any	—	Command to run while the user swipes the item.	1.2.0
`primaryAction`	Command	—	The action to trigger when the user selects the item. Ignored when `customLayoutName` has a value.	1.2.0
`primaryText`	String	—	Primary text to display for the item.	1.2.0
`ratingGraphicType`	String	`AVG`	The type of graphic to use for the rating. Set to `AVG` or `image`. On smaller viewports, the rating doesn't display due to space. For details about how to use the `AlexaRating` properties, see AlexaRating.	1.2.0
`ratingNumber`	Number	-1	A numeric rating between 0 and 5. When set to a positive number, displays the number as a star rating. Set to a negative number or omit to leave off the rating.	1.2.0
`ratingSlotMode`	String	—	Determines whether to display a single graphical asset for the rating, or build the rating from multiple image assets. When set to `single`, provide a single graphical asset in the `singleRatingGraphic` property. When `multiple`, provide the numeric rating in `ratingNumber`. On smaller viewports, the rating doesn't display due to space. For details about how to use the `AlexaRating` properties, see AlexaRating.	1.2.0
`ratingText`	String	—	Text to display next to the rating. Ignored when `ratingNumber` is a negative number or omitted.	1.2.0
`secondaryText`	String	—	Secondary text to display for the item.	1.2.0
`secondaryTextPosition`	String	`bottom`	The position to display the `secondaryText`. Set to `top` or `bottom`. The `secondaryText` aligns to the start of the `primaryText`.	1.2.0
`singleRatingGraphic`	Any	—	The graphic to display to represent the rating. Used when `ratingSlotMode` is `single`. You can provide either a reference to an AVG or the URL of an image. On smaller viewports, the rating doesn't display due to space. For details about how to use the `AlexaRating` properties, see AlexaRating.	1.2.0
`singleRatingGraphicWidth`	Dimension	—	The width of the bounding box for the single graphic that represents the rating. Used when `ratingSlotMode` is `single`. On smaller viewports, the rating doesn't display due to space. For details about how to use the `AlexaRating` properties, see AlexaRating.	1.2.0
`tertiaryText`	String	—	Tertiary text to display for the item.	1.2.0
`tertiaryTextPosition`	String	`right`	The position to display the `tertiaryText`. Set to `bottom` or `right`. When set to `right`, the `tertiaryText` displays above and to the right of the `primaryText`. When set to `bottom`, the `tertiaryText` displays below the `primaryText` and is left-aligned with the `primaryText`.	1.2.0
`theme`	String	`dark`	Set the dark or light color theme. The selected theme controls the colors used for the component.	1.2.0
`touchForward`	Boolean	`false`	When `true`, assume the user is close enough to touch the screen (3-foot viewing distance) and format the item with a smaller font size. When `false`, assume the user isn't close enough to touch the screen ("voice-forward") and use a larger font size.	1.2.0
`type`	String	—	Always set to `AlexaSwipeToAction`	1.2.0

AlexaSwipeToAction within an AlexaTextList

You can use AlexaSwipeToAction within an AlexaTextList to display a scrolling list of items that the user can swipe. Within the text list, set defaults for the AlexaSwipeToAction items with the following AlexaTextList properties that correspond to AlexaSwipeToAction properties:

swipeDirection
swipeActionIcon
swipeActionIconType
swipeActionIconForeground
swipeActionIconBackground
onSwipeMove
onSwipeDone
optionsButton1Text
optionsButton1Command
optionsButton2Text
optionsButton2Command

To enable swiping in the AlexaTextList, set swipeDirection to left or right.

For example, the following APL document and data source shows an AlexaTextList that allows the user to swipe items. The onSwipeDone property is defined at the list-level rather than at the individual item level. When the user completes a swipe, the device sends the skill a UserEvent request with information about the list item that the user swiped.

An AlexaTextList that uses swipe actions for the list items. The second item is partially swiped.

AlexaSwipeToAction examples

The following example shows some variations of AlexaSwipeToAction placed within a Container. The AlexaSwipeToAction items also set the text and actions for buttons to give TV users an alternative to swiping that they can navigate with a TV remote.

On a hub device, when you begin swiping an item, the header updates to show the swipe progress. When you complete the swipe, the header updates to show that the swipe is finished.

On a TV device, when you highlight an item with the remote, the item displays the two options buttons. When you select one of the buttons, the header updates to show that the selection is finished.

Copied to clipboard.

To learn how to test APL examples in the authoring tool, see Experiment with APL Examples in the Authoring Tool.

{
  "type": "APL",
  "version": "2024.2",
  "import": [
    {
      "name": "alexa-layouts",
      "version": "1.7.0"
    }
  ],
  "commands": {
    "ShowSwipeProgress": {
      "commands": [
        {
          "type": "SetValue",
          "componentId": "myHeaderId",
          "property": "headerSubtitle",
          "value": "Swipe in progress: ${(event.position * event.source.width)}"
        }
      ]
    },
    "ShowSwipeFinished": {
      "commands": [
        {
          "type": "SetValue",
          "componentId": "myHeaderId",
          "property": "headerSubtitle",
          "value": "@resultText"
        }
      ]
    },
    "ShowSelectionFinished": {
      "commands": [
        {
          "type": "SetValue",
          "componentId": "myHeaderId",
          "property": "headerSubtitle",
          "value": "@selectText"
        }
      ]
    }
  },
  "resources": [
    {
      "strings": {
        "headerSubtitleText": "Select or swipe the items",
        "resultText": "Done swiping!",
        "selectText": "You selected the item instead of swiping it."
      }
    },
    {
      "when": "${@viewportProfile == @tvLandscapeXLarge}",
      "strings": {
        "headerSubtitleText": "Use your remote to highlight an item and click a button.",
        "resultText": "Done selecting buttons!",
        "selectText": "You selected the entire item instead of a single option button."
      }
    }
  ],
  "mainTemplate": {
    "parameters": [
      "payload"
    ],
    "items": [
      {
        "type": "Container",
        "width": "100%",
        "items": [
          {
            "type": "AlexaHeader",
            "id": "myHeaderId",
            "headerTitle": "Swipe to Action Examples",
            "headerSubtitle": "@headerSubtitleText"
          },
          {
            "type": "AlexaSwipeToAction",
            "primaryText": "Primary text for a default swipe to action",
            "secondaryText": "Secondary text",
            "tertiaryText": "Tertiary text",
            "touchForward": true,
            "button1Text": "Button 1",
            "button1Command": {
              "type": "ShowSwipeFinished"
            },
            "button2Text": "Button 2",
            "button2Command": {
              "type": "ShowSwipeFinished"
            },
            "onSwipeMove": {
              "type": "ShowSwipeProgress"
            },
            "onSwipeDone": {
              "type": "ShowSwipeFinished"
            },
            "primaryAction": {
              "type": "ShowSelectionFinished"
            }
          },
          {
            "type": "AlexaSwipeToAction",
            "primaryText": "Swipe to action with a custom icon color",
            "actionIconForeground": "red",
            "touchForward": true,
            "button1Text": "Button 1",
            "button1Command": {
              "type": "ShowSwipeFinished"
            },
            "button2Text": "Button 2",
            "button2Command": {
              "type": "ShowSwipeFinished"
            },
            "onSwipeMove": {
              "type": "ShowSwipeProgress"
            },
            "onSwipeDone": {
              "type": "ShowSwipeFinished"
            },
            "primaryAction": {
              "type": "ShowSelectionFinished"
            }
          },
          {
            "type": "AlexaSwipeToAction",
            "primaryText": "Swipe to action with a custom background color",
            "actionIconForeground": "red",
            "actionIconBackground": "@colorSalmon800",
            "touchForward": true,
            "button1Text": "Button 1",
            "button1Command": {
              "type": "ShowSwipeFinished"
            },
            "button2Text": "Button 2",
            "button2Command": {
              "type": "ShowSwipeFinished"
            },
            "onSwipeMove": {
              "type": "ShowSwipeProgress"
            },
            "onSwipeDone": {
              "type": "ShowSwipeFinished"
            },
            "primaryAction": {
              "type": "ShowSelectionFinished"
            }
          }
        ]
      }
    ]
  }
}

Swipe in progress for an AlexaSwipeToAction item

Was this page helpful?

Provide feedback

Last updated: Nov 28, 2023