APL Base Component Properties (APL 2024.2)

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

A component is a primitive element that displays on the viewport.

In Alexa Presentation Language (APL), components are primitive visual components rendered by the client. For example, a Text component displays text on the screen. All APL components share a set of base properties.

Properties

All components support the following properties.

The "Default" column lists the default values of properties. All Required properties must be set or the component doesn't inflate. Properties with no default display a dash (—) in the "Default" column. The interpretation of no default is property-dependent. For example, not setting the speech property prevents a component from speaking text when you run the SpeakItem command. Not setting maxHeight lets the component grow arbitrarily tall, which is equivalent to setting maxHeight to a large number.

The "Styled" column identifies properties that you can set from a style. Directly specifying a value for a component property overrides any style-defined values. In the following example, the Text component always has an opacity of 0.5 regardless of the definition of myTextStyle:

    {
      "type": "Text",
      "opacity": 0.5,
      "style": "myTextStyle"
    }

The "Dynamic" column identifies properties that you can change dynamically with the SetValue command. Setting a dynamic property with SetValue overrides any style values. There is no mechanism to unset a dynamic property.

When a component is the source or target of an event, the following values are reported in event.source or event.target:

{
  "bind": Map,         // Access to component data-binding context
  "checked": Boolean,  // Checked state
  "disabled": Boolean, // Disabled state
  "focused": Boolean,  // Focused state
  "height": Number,    // Height of the component, in dp (includes the padding)
  "id": ID,            // ID of the component
  "opacity": Number,   // Opacity of the component [0-1]
  "pressed": Boolean,  // Pressed state
  "type": TYPE,        // Component type (e.g., "Frame", "Image")
  "uid": UID,          // Runtime-generated unique ID of the component
  "width": Number      // Width of the component, in dp (includes the padding)
}

Component-specific values are added to event.source and event.target.

accessibilityLabel

A text string used by a screen reader in accessibility mode.

actions

Assistive technology can programmatically interact with on-screen components when the user can't due to a disability. A component defines a set of actions for use with this type of technology. The actions property contains a list of action objects, where each action object has a name and a set of commands to run. The name of the action can be one of the standard actions or a custom action.

The following example shows a TouchWrapper that defines one standard action (activate) and one custom action (thumbsup).

{
  "type": "TouchWrapper",
  "actions": [
    {
      "name": "activate",
      "label": "Reply to user",
      "command": {
        "type": "SendEvent",
        "arguments": "Activated by action invocation"
      }
    },
    {
      "name": "thumbsup",
      "label": "Mark positively",
      "command": {
        "type": "SetValue",
        "property": "Rating",
        "value": 1
      }
    }
  ]
}

The actions property is an array of objects with the properties shown in the following table.

The label property provides a localized description of the action. Examples of labels include "remove item," and "reply."

The enabled property determines whether the action can be invoked. Disabled actions might be presented by an accessibility system, but marked as not available.

If two actions in the action list have the same name property, the first one is used. The second action is ignored even when the first action isn't enabled.

Standard actions are reserved names associated with standard event handlers. When you provide a standard action in the action list without a command array, invoking the action invokes the designated event handler. There are two types of standard actions: implicit and explicit. To enable an explicit action, you must specify the action in the component actions property. Implicit actions are enabled by default, but you can override the commands.

The following table lists the standard actions.

The following example shows a TouchWrapper component that defines an activate action. The activate action doesn't have a command array. Therefore, invoking this action invokes the commands defined in the onPress property.

{
  "type": "TouchWrapper",
  "onPress": {
    "type": "SendEvent",
    "arguments": "I was pressed!"
  },
  "actions": [
    {
      "name": "activate",
      "label": "message to server"
    }
  ]
}

Because the Tap gesture is analogous to a "press," the onTap handler runs as a fallback in cases where an "activate" action would have resulted in a call to onPress but that event handler isn't provided.

In the following example, the "activate" action calls the onTap handler because the "activate" action doesn't have a command array and the onPress handler isn't provided.

{
  "type": "TouchWrapper",
  "gestures": [
    {
      "type": "Tap",
      "onTap": {
        "type": "SendEvent",
        "arguments": "This is called for the activate action"
      }
    }
  ],
  "actions": [
    {
      "name": "activate",
      "label": "message to server"
    }
  ]
}

You can disable the implicit standard actions. The following example disables accessibility scrolling for a Pager.

{ "type": "Pager", "actions": [ { "name": "scrollforward", "label": "Disabled scrolling", "enabled": false } ] }

bind

The bind property of a component extends the data-binding context for the component and its children with local bound variables. For details about bound variables, see APL Bound Variables.

checked

The checked property sets the checked state of the component. You can use component states when you define styles.

Use the SetValue command to change the checked state on a component.

Set the inheritParentState property to true on child components to inherit the checked state of the parent.

disabled

The disabled property sets the disabled state of the component. You can use component states when you define styles. When disabled is true, the component doesn't respond to touch events.

Use the SetValue command to change the disabled state on a component.

Set the inheritParentState property to true on child components to inherit the disabled state of the parent.

display

The display property of a component determines whether the component displays on the screen and how the component affects the layout calculation. Set to one of the following values shown in the following table.

The display property doesn't affect the data-binding context, ordinals, and indices used when constructing components. For example, in a container with three children, if the first child has display=none, that child is still data-bound with index=0 and the next child has index=1.

The following table shows the different ways to hide and show content.

The Focusable? column is for accepting keyboard focus. The Touchable? column is for responding to touch events. When display is invisible or none, the touch events pass through the component as if it wasn't there and are processed by the next component down in the stacking order. The normal display components don't pass touch events through, but they only respond to touch events when disabled is false.

In APL 2024.2 or later, the pointerEvents property can override the behavior shown in the Touchable? and Touch and hover passes through? columns. When pointerEvents is none, the component and its children are never the target of pointer events. The events pass through to the next eligible component in the z-order.

The descendants of a component with display=invisible aren't drawn. This means that an invisible component doesn't have visible descendants. Similarly, when a component has display=none, the component and all its descendants are removed from the display hierarchy and take no space on the screen.

entities, entity

Opaque entity data. Alexa devices pass the entity data back to the skill as context. Use this property to provide information about the purpose of the component to use in your skill code.

Set this property to an array of objects. Each object can have the properties id, type, and value. Any other properties aren't included in the visual context.

For details about the visual context, see APL Visual Context in the Skill Request.

handleTick

An array of tick event handlers to run as time passes.

The event generated for a tick event handler has the following form.

"event": {
  "source": {
    "type": "COMPONENT_TYPE", // The type of the component (e.g., "Pager", "TouchWrapper")
    "handler": "Tick",
    ...                     // Component source properties
  }
}

The event.source.type property contains the name of the component, such as "TouchWrapper" or "ScrollView". Refer to Event source for a description of event.source properties.

The component tick event handler runs in the component data-binding context.

handleVisibilityChange

An array of visibility change handlers to run when the visible region or overall opacity of the component changes.

The component visibility change handler runs in the component data-binding context.

height

Value used to calculate the final height of the component. You can set height in one of four different ways:

• Absolute dimension – A value such as 100dp, 25vh, or 24px fixes the height of the component. A pure number such as 50.2 is interpreted as a dp value. Therefore, 50.2 is the same as "50.2dp". For more about absolute dimensions, see Absolute dimensions.
• Relative dimension – A value such as 25% sets the height of the component to a percentage height of its parent component. The parent component must have a defined dimension for this to work. If the parent component has a height of auto, using a relative height for a child component is undefined and sets to zero. For more about relative dimensions, see relative dimensions.
• Auto dimension – With auto, the component takes on the height of its children plus any padding. For a Frame, the height also incudes the height of its borders.
• Dimension not set – When the height of a component isn't specified, the height reverts to the default height for the component. Refer to the specific component documentation for default heights.

You can set height to a value that's smaller than the sum of the vertical padding, borders, and heights of any contained children. In this scenario, the component clips the contents to the final component height.

Use relative dimensions for the component height whenever possible. A component with relative dimensions for the size can adjust to differently-sized screens. For more about making sure your documents look good on different devices, see the following:

• Build Responsive APL Documents
• Support Tablets and Other Devices that Can Change Size

id

An identifier you can define for an instance of the component. The id locates a particular component in the view hierarchy. The regular expression for a valid id is [_a-zA-Z][_a-zA-Z0-9]*. Although recommended, the id isn't required to be unique. Internally, APL assigns each component an internal ID (uid).

The following example shows a Container with a Text and Image component.

{
  "type": "Container",
  "items": [
    {
      "type": "Text",
      "id": "myText"
    },
    {
      "type": "Image"
    }
  ]
}

The Container, Text, and Image are each assigned unique internal id values such as :1001, :1002, and :1003 respectively. Alexa reports both the generated internal uid and developer-assigned id values in the visual context.

You can use the id for component in the selector syntax to target a component with a command.

inheritParentState

Replaces the component state with the state of the parent of the component. Used for components that should visually change appearance based on the state of the parent. For example, you might want a Text component inside of a TouchWrapper to change color when the user presses the TouchWrapper. If you set inheritParentState to true, the Text component changes state whenever the TouchWrapper changes state.

layoutDirection

Specifies the direction in which the component renders. Set this property to one of the following:

• inherit – (Default). The component inherits the layoutDirection from its parent. When the component is directly under mainTemplate, the component inherits the layoutDirection specified in the document.
• LTR – The component uses the left-to-right direction.
• RTL – The component uses the right-to-left direction.

The layoutDirection for the component determines how the paddingStart and paddingEnd properties override paddingLeft and paddingRight.

The layoutDirection property determines the internal layout of the following components:

• Container
• Text
• EditText
• Touchable components
• Pager
• Sequence
• GridSequence

The recommended way to set layoutDirection is to set the document-level layoutDirection to a value in your data source. Use the component-level layoutDirection if a specific component in your layout requires a different setting than the overall document-level layoutDirection.

The following example displays multiple text blocks in a Container. All the text blocks use the document default layoutDirection except one, which overrides the value.

In this example, changing the exampleDataSource.responseLanguage.layoutDirection in the data source automatically changes the layout shown on the screen. Use the locale provided in the request sent to your skill to determine the values for layoutDirection and lang and then pass these values to APL in your data source.

For details about supporting different languages and determining the locale of the request, see Develop Skills in Multiple Languages.

maxHeight

A dimension that limits the maximum height of a component. The component is never taller than the maxHeight. The maxHeight property should always be greater than or equal to the minHeight property. If the maxHeight property isn't specified, it's assumed to be infinite.

maxWidth

A dimension that limits the maximum width of a component. The component is never wider than the maxWidth. The maxWidth property should always be greater than or equal to the minWidth property. If the maxWidth isn't specified, it's assumed to be infinite.

minHeight

A dimension that limits the minimum height of a component. The component is never shorter than the minHeight. The minHeight property should always be less than or equal to the maxHeight property. If the minHeight property isn't specified, it's assumed to be zero.

minWidth

A dimension that limits the minimum width of a component. The component is never narrower than the minWidth. The minWidth property should always be less than or equal to the maxWidth property. If the minWidth property isn't specified, it's assumed to be zero.

onCursorEnter

Commands to run when a cursor enters the active region for a component.

The event.source.value property contains the standard source value for the component. For details, see: Event source property.

A component where the disabled state is true doesn't respond to changes in cursor events and doesn't run any commands assigned to the onCursorEnter event handler. If the cursor is over a disabled component and then component is enabled, an onCursorEnter event is generated for the component.

The event generated has the following form.

"event": {
  "source": {
    "type": COMPONENT_TYPE, // The type of the component (e.g., "Pager", "TouchWrapper")
    "handler": "CursorEnter",
    ...                     // Component source properties
  }
}

The event.source.type property contains the name of the component, such as "TouchWrapper" or "ScrollView". Refer to Event source for a description of event.source properties.

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

onCursorExit

Commands to run when a cursor exits the active region for a component.

The event.source.value property contains the standard source value for the component. For details, see: Event source property.

A component where the Disabled state is true doesn't respond to changes in cursor events and doesn't run any commands assigned to the onCursorExit event handler. If the cursor is over a disabled component and then component is enabled, an onCursorExit event is generated for the component.

The event generated has the following form.

"event": {
  "source": {
    "type": "COMPONENT_TYPE", // The type of the component (e.g., "Pager", "TouchWrapper")
    "handler": "CursorExit",
    ...                     // Component source properties
  }
}

The event.source.type property contains the name of the component, such as "TouchWrapper" or "ScrollView". Refer to Event source for a description of event.source properties.

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

onMount

Commands to run when the component is first displayed. Use the mount commands for visual transitions between screens. The event.source.value remains unset during mount.

The onMount command runs when the document loads. Component onMount commands run even if the component itself is invisible or otherwise not displayed on the screen.

The event generated has the following form.

"event": {
    "source": {
      "type": "COMPONENT_TYPE", // The type of the component (e.g., "Pager", "TouchWrapper")
      "handler": "Mount",
      ...                     // Component source properties
    }
  }

The event.source.type property contains the name of the component, such as "TouchWrapper" or "ScrollView". Refer to Event source for a description of event.source properties.

The onMount event handler runs in normal mode in the component data-binding context. For details about how the component-level and document-level onMount handlers interact, see the document onMount property.

onLayout

Commands to run when the layout calculation for the component changes.

This handler is invoked when the component initially displays (onMount) and then again whenever the layout for the component changes.

This handler is invoked immediately after the layout has been calculated, but the new layout might not yet be reflected on the screen at the time the event is received, especially if a layout (dimension) animation is in progress.

The event.source.value property contains the standard source value for the component. For details, see: Event source property.

The event generated has the following form.

"event": {
  "source": {
    "type": COMPONENT_TYPE,  // The type of the component (e.g., "Pager", "TouchWrapper")
    "handler": "Layout",
    ...                      // Component source properties
  },
  "width": NUMBER,     // Width of the component after the layout changes.
  "height": NUMBER,    // Height of the component after the layout changes.
  "x": NUMBER,         // Component X coordinate inside the parent component.
  "y": NUMBER          // Component Y coordinate inside the parent component.
}

The following example uses onLayout to resize a horizontal Sequence to show four Text components of varying size, each of which uses auto for its width. The onLayout handler on the Text component uses a when condition to run the command one time for each of the first four child items. The SetValue command increases the width of the Sequence by enough to show the Text item.

• APL Document

{
  "type": "APL",
  "version": "2024.3",
  "theme": "dark",
  "mainTemplate": {
    "items": [
      {
        "type": "Container",
        "height": "100%",
        "width": "100%",
        "padding": "16dp",
        "bind": [
          {
            "name": "TotalItemsToShow",
            "value": ["First item", "TEXT 1", "Third item", "T3", "TEXT 4", "TEXT 5", "TEXT 6"]
          }
        ],
        "items": [
          {
            "type": "Sequence",
            "scrollDirection": "horizontal",
            "data": "${TotalItemsToShow}",
            "height": "auto",
            "width": 100,
            "maxWidth": "75%",
            "items": {
              "type": "Text",
              "width": "auto",
              "height": "auto",
              "text": "${data}",
              "spacing": 10,
              "onLayout": [
                {
                  "when": "${index <= 3}",
                  "type": "SetValue",
                  "componentId": ":parent()",
                  "property": "width",
                  "value": "${event.x + event.width}"
                }
              ]
            }
          },
          {
            "type": "Text",
            "id": "showResult",
            "text": "Total items ${TotalItemsToShow.length} (scroll to see all)"
          }
        ]
      }
    ]
  }
}

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

onSpeechMark

Commands to run when the audio specified in the speech property encounters a speech mark.

For more details about speech marks, see Speech Marks - Amazon Polly

The event.source.value property contains the standard source value for the component. For details, see: Event source property.

The onSpeechMark event runs during the duration of the SpeakItem command when the speech property on the component is set to audio that contains speech marks.

The event generated has the following form.

"event": {
  "source": {
    "type": COMPONENT_TYPE,  // The type of the component (e.g., "Pager", "TouchWrapper")
    "handler": "SpeechMark",
    ...                      // Component source properties
  },
  "markType": MARK_TYPE,     // Type of speech mark
  "markTime": NUMBER,        // Start time of speech mark, in milliseconds
  "markValue": STRING
}

Each speech mark has a type, as shown in the following table.

For example, a word speech mark generated when the SpeakItem command reads the word "right" generates the following event.

"event": {
"source": {
    "type": "Text",
    "handler": "SpeechMark",
  },
  "markType": "word",
  "markTime": 3562,
  "markValue": "right"
}

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

The following example shows an APL document that uses SpeakItem to read a short paragraph containing directional words. The onSpeechMark handler runs commands that display a vector graphic arrow that corresponds to the words in the paragraph. For example, the arrow points to the right when Alexa reads the word "right" and points down when Alexa reads the word "down." The example uses a when condition on the onSpeechMark handler to update the vector graphic based on the words "right," "left," "up," "down," and "disappear."

Example document: Using speech marks to sync animation with speech  

{
  "type": "APL",
  "version": "2022.2",
  "theme": "dark",
  "import": [
    {
      "name": "alexa-layouts",
      "version": "1.6.0"
    }
  ],
  "graphics": {
    "DirectionalArrow": {
      "description": "Displays an arrow. Set the Direction parameter to change the direction.",
      "type": "AVG",
      "version": "1.2",
      "parameters": [
        "Direction"
      ],
      "width": 100,
      "height": 100,
      "items": [
        {
          "type": "path",
          "description": "Right",
          "strokeOpacity": "${Direction == 1 ? 1.0 : 0.0}",
          "pathData": "M0,50 100,50 50,0 100,50 50,100",
          "stroke": "#FF0000",
          "strokeWidth": 5
        },
        {
          "type": "path",
          "description": "Down",
          "strokeOpacity": "${Direction == 2 ? 1.0 : 0.0}",
          "pathData": "M50,0 50,100 100,50 50,100 0,50",
          "stroke": "#4CAF50",
          "strokeWidth": 5
        },
        {
          "type": "path",
          "description": "Left",
          "strokeOpacity": "${Direction == 3 ? 1.0 : 0.0}",
          "pathData": "M100,50 0,50 50,100 0,50 50,0",
          "stroke": "#FFEB3B",
          "strokeWidth": 5
        },
        {
          "type": "path",
          "description": "Up",
          "strokeOpacity": "${Direction == 4 ? 1.0 : 0.0}",
          "pathData": "M50,100 50,0 0,50 50,0 100,50",
          "stroke": "#2196F3",
          "strokeWidth": 5
        }
      ]
    }
  },
  "mainTemplate": {
    "parameters": [
      "magicArrow"
    ],
    "items": [
      {
        "type": "Container",
        "items": [
          {
            "type": "AlexaHeader",
            "headerTitle": "${magicArrow.properties.headerTitle}"
          },
          {
            "type": "AlexaButton",
            "buttonText": "Click to Start!",
            "alignSelf": "center",
            "primaryAction": [
              {
                "type": "SpeakItem",
                "componentId": "magicArrowGraphic"
              }
            ]
          },
          {
            "type": "Text",
            "text": "${magicArrow.properties.directionPlainText}",
            "style": "textStyleBody",
            "textAlignVertical": "center",
            "maxLines": "${@viewportProfile == @hubRoundSmall ? 2 : '' }",
            "padding": [
              "@marginHorizontal",
              "@spacingSmall"
            ]
          },
          {
            "type": "VectorGraphic",
            "id": "magicArrowGraphic",
            "alignSelf": "center",
            "Direction": 0,
            "source": "DirectionalArrow",
            "speech": "${magicArrow.properties.directionSpeech}",
            "onSpeechMark": [
              {
                "when": "${event.markValue == 'right'}",
                "type": "SetValue",
                "property": "Direction",
                "value": 1
              },
              {
                "when": "${event.markValue == 'down'}",
                "type": "SetValue",
                "property": "Direction",
                "value": 2
              },
              {
                "when": "${event.markValue == 'left'}",
                "type": "SetValue",
                "property": "Direction",
                "value": 3
              },
              {
                "when": "${event.markValue == 'up'}",
                "type": "SetValue",
                "property": "Direction",
                "value": 4
              },
              {
                "when": "${event.markValue == 'disappear'}",
                "type": "SetValue",
                "property": "Direction",
                "value": 0
              }
            ]
          }
        ]
      }
    ]
  }
}

Example data source: Using speech marks to sync animation with speech  

{
  "magicArrow": {
    "properties": {
      "headerTitle": "Watch the magic arrow",
      "narration": "<speak>I'm going to display a magic arrow that syncs with my voice. First it points to the left. Then I will tell it to point right. The arrow can point down, and it can also point up. Finally, I will make it disappear.</speak>"
    },
    "transformers": [
      {
        "transformer": "ssmlToSpeech",
        "inputPath": "narration",
        "outputName": "directionSpeech"
      },
      {
        "transformer": "ssmlToText",
        "inputPath": "narration",
        "outputName": "directionPlainText"
      }
    ]
  }
}

opacity

Applies a uniform opacity to this component and the children of the component. The opacity is a number from 0 through 1. Numbers outside this range are clipped to the range. The actual displayed opacity of a component is the product of the opacity value and all the ancestor opacity values.

For example, if the opacity for the current component is 0.5 and its parent opacity is 0.8, the actual displayed opacity of the component is 0.4. Setting the opacity to 0 hides the component, but doesn't remove it from the component hierarchy.

padding

The padding properties add space around a component. The calculated component width and height define the outer bounds of the component and the clipping boundary. The values you provide for padding specify the space between the outer bounds of the component and the content. The values you provide for the padding properties must be non-negative, absolute dimensions.

You can specify the padding values with the padding property and with separate properties for each side of the component:

• padding – Accepts an array of values to set padding for multiple sides of the component.
• paddingBottom – Padding for the bottom of the component.
• paddingLeft – Padding for the left side of the component.
• paddingRight – Padding for the right side of the component.
• paddingTop – Padding for the top of the component.
• paddingStart – Padding to override either the left or right padding, depending on the layoutDirection for the component. For details, see paddingStart, paddingEnd.
• paddingEnd – Padding to override either the left or right padding, depending on the layoutDirection for the component. For details, see paddingStart, paddingEnd.

The padding property is an array of one to four values, ordered by left, top, right, and bottom. When you provide fewer than four values in this array, the padding property expands to a four-element array according to the rules shown in the following table.

The other four padding properties override the values specified in padding for the specific side. The following examples show three equivalent ways to specify padding. Each example results in padding set to 10 for the left and right, 20 for the top, and 40 for the bottom.

The single padding property with four values sets the left padding to 10, the top to 20, the right to 10, and the bottom to 40.

{
  "padding": [10,20,10,40]
}

The single padding property with two values sets the left and right padding to 10 and the top and bottom to 20. Then, the paddingBottom property overrides the bottom to change it to 40.

{
  "padding": [10,20],
  "paddingBottom": 40
}

The single padding property with one value sets the padding for all four sides to 10. Then, the paddingTop overrides the top padding and sets it to 20. The paddingBottom overrides the bottom padding and sets it to 40.

{
  "padding": 10,
  "paddingTop": "20dp",
  "paddingBottom": 40
}

paddingStart, paddingEnd

When specified, the paddingStart and paddingEnd properties override paddingLeft and paddingRight. The override depends on the layoutDirection property.

For example, when layoutDirection is LTR, the following component has 15 for the left padding and 20 for the right padding. When layoutDirection is RTL, the component has 15 for the right padding and 20 for the left:

{
    "paddingLeft": 10,
    "paddingRight": 10,
    "paddingStart": 15,
    "paddingEnd": 20
}

preserve

An array of dynamic component properties and bound properties to save when reinflating the document with the Reinflate command. The Reinflate command preserves these properties if the old component id matches the new id. The component properties specified in preserve aren't saved if the component doesn't have an id.

The following example saves the checked state of a TouchWrapper.

{
  "type": "TouchWrapper",
  "id": "MyUniqueID",
  "preserve": ["checked"]
}

You can also save bound properties. The following example defines a bound property called Counterand a TouchWrapper that increments Counter. The preserve array contains the name of this bound property. This saves the value in Counter when the document reinflates.

{
  "type": "TouchWrapper",
  "id": "MyCounterButton",
  "bind": [
    {
      "name": "Counter",
      "value": 0
    }
  ],
  "preserve": [
    "Counter"
  ],
  "items": {
    "type": "Text",
    "text": "You have pushed this button ${Counter} times"
  },
  "onPress": [
    {
      "type": "SetValue",
      "property": "Counter",
      "value": "${Counter + 1}"
    }
  ]
}

In addition to dynamic properties and bound properties, some components have component-specific preserve property names for saving component-specific data. For example, components that scroll include preserve properties for saving the scroll position. See the preserve property on the following components:

• FlexSequence
• GridSequence
• Pager
• ScrollView
• Sequence
• Video

The preserve properties evaluate in the data-binding context of the component with the event properties augmented by the new configuration values. This allows a dynamic choice of which properties to preserve.

pointerEvents

Determines whether the component can become the target of pointer events. Pointer events include, but aren't limited to, touch or cursor events (up, move, down, cancel), gestures and hover.

This property accepts the following values.

In the following example, a VectorGraphic that displays a gradient is layered on top of a Sequence, covering a portion of the Sequence at the bottom. The default behavior is for the VectorGraphic to capture any touch events and not pass them through, so touching and dragging near the bottom of the Sequence would not scroll. With pointerEvents set to none, the user can touch and drag anywhere on the Sequence to scroll the content.

• APL Document

{
  "type": "APL",
  "version": "2024.3",
  "theme": "dark",
  "background": "#232F3E",
  "mainTemplate": {
    "items": {
      "type": "Container",
      "height": 400,
      "width": 400,
      "alignItems": "center",
      "items": [
        {
          "type": "Sequence",
          "height": "100%",
          "width": "100%",
          "data": ["red", "blue", "green", "yellow", "gray", "purple"],
          "item": {
            "type": "Frame",
            "height": 125,
            "width": "100%",
            "background": "${data}"
          },
          "lastItem": [
            {
              "type": "Text",
              "text": "End of list",
              "textAlign": "center",
              "textAlignVertical": "center",
              "height": 125
            }
          ]
        },
        {
          "type": "VectorGraphic",
          "id": "OverlayEffect",
          "position": "absolute",
          "height": 100,
          "width": 400,
          "top": 300,
          "source": "GradientOverlay",
          "pointerEvents": "none"
        }
      ]
    }
  },
  "graphics": {
    "GradientOverlay": {
      "type": "AVG",
      "version": "1.2",
      "width": 400,
      "height": 100,
      "resources": [
        {
          "gradients": {
            "linearGradient": {
              "inputRange": [
                0,
                0.8
              ],
              "colorRange": [
                "#ffffff00",
                "#000000ff"
              ],
              "type": "linear",
              "x2": 0,
              "y2": 1,
              "x1": 0,
              "y1": 0
            }
          }
        }
      ],
      "items": [
        {
          "type": "path",
          "pathData": "M0,0 L400,0 L400,100 L0,100 Z",
          "fill": "@linearGradient"
        }
      ]
    }
  }
}

role

The role provides machine-readable information about the purpose of the component. Some assistive technologies use this information. For example, a screen reader might use the role when describing a component displayed on the screen.

APL supports the following roles on components:

• adjustable – The component can be "adjusted" (for instance, a slider is adjustable).
• alert – A region with important information to be presented to the user.
• button – An input that triggers general actions when clicked or pressed. Related to the link role.
• checkbox – A check box which can be checked, unchecked, or have mixed checked state.
• combobox – Represents a combo box, which allows the user to select among several choices.
• header – Acts as a header for a content section (for example, the title of a navigation bar).
• image – The component should be treated as an image. Use imagebutton if this component also acts as a button.
• imagebutton – The component is an image that also works as a button.
• keyboardkey – The component acts as a keyboard key.
• link – An input when triggered causes the user agent to navigate to a new resource or display.
• list – A region containing a list of listitem.
• listitem – An individual item in a list. A listitem must have list ancestor.
• menu – The component is a menu of choices.
• menubar – The component is a container of multiple menus.
• menuitem – Represents an item within a menu.
• progressbar – The component indicates progress of a task.
• radio – The component acts as a radio button.
• radiogroup – The component contains a group of radio buttons.
• scrollbar – Represents a scroll bar that controls the scrolling of a region.
• search – A text field component that should also be treated as a search field.
• spinbutton – A button which opens a list of choices.
• summary – Used when a component can be used to provide a quick summary of current conditions in the app when the app first launches.
• switch – Represent a switch which can be turned on and off, as opposed to checked/unchecked.
• tab – Represents a tab. A tab should have a tablist ancestor.
• tablist – A region containing a list of tab components.
• text – The component should be treated as static text that can't change.
• timer – A region displaying a counter that indicates elapsed time or time remaining.
• toolbar – Used to represent a tool bar (a container of action buttons or components).

shadowColor

The color of the shadow. This color normally contains some transparency. The overall opacity is also applied to the shadow color.

shadowHorizontalOffset

The horizontal drawing offset of the shadow. Positive numbers move the shadow to the right; negative numbers move it to the left.

shadowRadius

The blur radius of the shadow.

shadowVerticalOffset

The vertical drawing offset of the shadow. Positive numbers move the shadow down; negative numbers move it up.

speech

Opaque data provided by a transformer that converts content to speech. The following transformers output audio that you can use with the speech property:

• ssmlToSpeech
• textToSpeech
• aplAudioToSpeech

Use a data-binding expression to bind the speech property to the output of the transformer. Then use the SpeakItem or SpeakList commands to tell Alexa to speak the content.

style

A named style to use to set properties on the component.

transform

The transformation array is an array of transformation values applied to the component. For example:

"transform": [ { "rotate": 30 }, { "scaleX": 1.5 }, { "translateX": 10 }]

Each individual transform is an object with a single property and associated value. Transformations are applied from right to left (following the web standard). In the previous example the component first shifts 10 dp to the right, scales up by 50%, and then rotates about its center 30 degrees.

Each element in the transformation array is one of the following:

You can gather transformation properties from the same group into a single object. For example, the following are equivalent:

[ { "scaleX": 3.0, "scaleY": 2.0} ]
[ { "scale": 3.0, "scaleY": 2.0 } ]
[ { "scaleX": 3.0 }, { "scaleY": 2.0 } ]
[ { "scale": 2.0 }, { "scaleX": 1.5 } ]

Transformations are cumulative. The final example scales the X-axis by 1.5, and then scales both axes by 2.0, giving a final scaling of { "scaleX": 3.0, "scaleY": 2.0 }.

Transformations apply to components after the document layout is calculated using the default bounds for the component. As a result, transformations don't effect the document flow for any components other than the transformed component and its children.

The translation values support both absolute dimensions (such as 10px or 20dp) as well as relative dimensions (such as 30%). The relative dimensions are calculated based on the unscaled component width and height. The following example rotates a component 45 degrees about its bottom-right corner:

"transform": [
  { "translateX": "50%", "translateY": "50%" },
  { "rotate": 45 },
  { "translateX": "-50%", "translateY": "-50%" }
]

The default bounds of a component are the bounds of a component before the transformations defined in the transform property are applied.

The transformed bounds of a component are the bounds of a component after the transformations defined in the transform property are applied.

type

Specifies the particular component to inflate. It can be one of the primitive components listed in this section or can be a named layout.

when

If the when expression is true, inflate the component. If false, ignore the component and all child components.

width

Value used to calculate the final width of the component. You can set width in one of four different ways:

• Absolute dimension – A value such as 100dp, 25vh, or 24px fixes the width of the component. A pure number such as 50.2 is interpreted as a dp value. Therefore, 50.2 is the same as "50.2dp". For more about absolute dimensions, see Absolute dimensions.
• Relative dimension – A value such as 25% sets the width of the component to a percentage width of its parent component. The parent component must have a defined dimension for this to work. If the parent component has a width of auto, using a relative width for a child component is undefined and sets to zero. For more about relative dimensions, see relative dimensions.
• Auto dimension – With auto, the component takes on the width of its children plus any padding. For a Frame, the width also incudes the width of its borders.
• Dimension not set – When the width of a component isn't specified, the width reverts to the default width for the component. Refer to the specific component documentation for default widths.

You can set width to a value that's smaller than the sum of the horizontal padding, borders, and widths of any contained children. In this scenario, the component clips the contents to the final component width.

Use relative dimensions for the component width whenever possible. A component with relative dimensions for the size can adjust to differently-sized screens. For more about making sure your documents look good on different devices, see the following:

• Build Responsive APL Documents
• Support Tablets and Other Devices that Can Change Size

Shadow notes

Text components generate shadows that follow the text shape. All other types of components generate shadows that are rectangular boxes surrounding the transformed bounds of the component (including the padding). Component shadows are clipped to their parent container.

Component shadows are drawn in standard drawing order. That means that the shadow of a component later in the drawing order overlaps components drawn earlier. Add space around the components to make sure that the component shadows don't overlap or get clipped unnecessarily.

Related topics

• APL Components
• Actionable Component Properties
• Touchable Component Properties
• Multi-child Component Properties
• Alexa Design Guide: Alexa Presentation Language

Last updated: Nov 22, 2024