RemoveItem Command

RemoveItem requires APL 2023.3 or later. Provide an alternate experience for devices running older versions of APL.

Removes a component from an inflated document and adjusts the layout reflect the change in structure.

Properties

The RemoveItem command has the properties shown in the following table, in addition to the common command properties. Set the type property to RemoveItem.

In the following table, the "Default" column shows "Required" for properties that must have a value for the command to run. Otherwise it displays the default value, which might be none.

Property Type Default Description

componentId

Selector

:source

The component to remove.

componentId

A selector that identifies the component or layout to remove. If the selector doesn't resolve to an existing component, the RemoveItem command does nothing.

Situations in which RemoveItem has no effect

The RemoveItem command has no effect on the inflated document in the following scenarios:

  1. The targeted component doesn't exist.
  2. The targeted component was inflated by data array inflation.

RemoveItem and layout adjustments

The following document defines a Container with the ID main and with two Text components. The components display in a column, one before the other.

{
  "type": "APL",
  "version": "2023.3",
  "mainTemplate": {
    "items": [
      {
        "type": "Container",
        "id": "main",
        "items": [
          {
            "type": "Text",
            "id": "hello",
            "text": "Hello, world!",
            "textAlign": "center",
            "textAlignVertical": "center",
            "grow": 1
          },
          {
            "type": "Text",
            "id": "bye"
            "text": "Goodbye, world!",
            "textAlign": "center",
            "textAlignVertical": "center",
            "grow": 1
          }
        ]
      }
    ]
  }
}
A wire frame representing the inflation of document with a single text component
A wire frame representing a document with two Text components

The following RemoveItem command removes the component with the id bye.

{
  "commands" : [
    {
      "type": "RemoveItem",
      "componentId": "bye"
    }
  ]
}

The layout adjusts to accommodate the removed component. The height of the first original Text component doubles due to the use of the grow property.

A wire frame representing the document after removing a Text component
A wire frame representing the document after removing a Text component

RemoveItem example

The following example uses a layout with a Frame component to show a border around the two components. The example runs the RemoveItem command five seconds after inflating the document to remove the second instance of the TextFrame layout. Refresh the page to reinflate the document and see the RemoveItem update.

In the example, the onChildrenChanged handler on the Container uses SendEvent to send the following UserEvent request to the skill after the RemoveItem command:

{
  "type": "Alexa.Presentation.APL.UserEvent",
  "requestId": "amzn1.echo-api.request.1",
  "timestamp": "2023-10-20T20:25:59Z",
  "locale": "en-US",
  "arguments": [
    {
      "uid": ":1003",
      "action": "remove"
    }
  ],
  "components": {},
  "source": {
    "type": "Container",
    "handler": "ChildrenChanged",
    "id": "main"
  },
  "token": "removeItemBasicFrameToken"
}

Test the example with a skill to test SendEvent.

For an example of using RemoveItem combined with InsertItem to remove an item from a single-child component and then insert a new item, see Insert into a single-child component.

Was this page helpful?

Last updated: Nov 28, 2023