APL Base Component Properties


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.

Property Type Default Styled Dynamic Description Version added
accessibilityLabel String No Yes Voice-over reads this string when the user selects this component 1.1
action, actions Array of actions [] Yes No Programmatic equivalents for complex touch interactions  
bind Array of Binding No No Expressions to add to the data binding context 1.0
description String No No Optional description of this component 1.0
checked Boolean false No Yes When true, this component has the checked state set. 1.1
disabled Boolean false No Yes When true, this component doesn't respond to touch or focus. 1.1
display String (invisible, none, normal) normal Yes Yes Determines whether the component displays on the screen. 1.1
entities, entity Array of Entities No Yes Opaque data used to clarify references in Alexa 1.0
handleTick Array of tick handlers [] No No Tick handlers to invoke as time passes  
handleVisibilityChange Array of visibility change handlers [] No No Visibility handlers to invoke when visibility of the component changes.  
height Positive Dimension auto Yes Yes The requested height of the component. 1.0
id String No No Reference name of the component, used for navigation and events. A valid component ID match the regular expression [_a-zA-Z][_a-zA-Z0-9]*. 1.0
inheritParentState Boolean false No No When true, replace the component state with the state of the parent component. 1.0
layoutDirection String. Set to LTR, RTL, inherit "inherit" Yes Yes The direction in which the component renders. Set this property for either left-to-right or right-to-left languages. 1.7
maxHeight Positive Dimension <none> Yes Yes The maximum allowed height of this component. 1.0
maxWidth Positive Dimension <none> Yes Yes The maximum allowed width of this component. 1.0
minHeight Non-negative Dimension 0 Yes Yes The minimum allowed height of this component. 1.0
minWidth Non-negative Dimension 0 Yes Yes The minimum allowed width of this component. 1.0
onMount Array of command No No Command to run when the component is first displayed. 1.1
onCursorEnter Array of command [] No No Commands to run when a cursor (mouse pointer) enters the active region for the component. 1.2
onCursorExit Array of command [] No No Commands to run when a cursor (mouse pointer) exits the active region for the component. 1.2
onSpeechMark Array of command [] No No Commands to run when the audio specified in the speech property encounters a speech mark. 2023.1
opacity Number 1.0 Yes Yes Opacity of this component and children. 1.0
padding Array of non-negative Absolute Dimension [] Yes Yes Space to add on the sides of the component 1.6
paddingBottom Non-negative Absolute Dimension 0 Yes Yes Space to add to the bottom of this component. 1.0
paddingEnd Non-negative Absolute Dimension <none> Yes Yes Space to add to the end edge of this component. The end edge is either the left or right side of the component, depending on the layoutDirection for the component. 1.7
paddingLeft Non-negative Absolute Dimension 0 Yes Yes Space to add to the left of this component. 1.0
paddingRight Non-negative Absolute Dimension 0 Yes Yes Space to add to the right of this component. 1.0
paddingStart Non-negative Absolute Dimension <none> Yes Yes Space to add to the start edge of this component. The start edge is either the left or right side of the component, depending on the layoutDirection for the component. 1.7
paddingTop Non-negative Absolute Dimension 0 Yes Yes Space to add to the top of this component. 1.0
preserve Array of string &mdash; No No Properties to save when reinflating the document with the Reinflate command. 1.6
role String Yes No Role or purpose of the component  
shadowColor Color transparent Yes Yes Shadow color 1.2
shadowHorizontalOffset Absolute Dimension 0 Yes Yes Horizontal offset of the shadow 1.2
shadowRadius Non-negative Absolute Dimension 0 Yes Yes Shadow blur radius 1.2
shadowVerticalOffset Absolute Dimension 0 Yes Yes Vertical offset of the shadow 1.2
speech Opaque <none> No No Transformed speech information for audio playback 1.0
style Style No No Named style or styles to apply. 1.0
transform Array of transform No Yes Array of transformations. 1.1
type String Required No No The type of the component. 1.0
when Boolean true No No If it evaluates to false, this component doesn't inflate. 1.0
width Positive Dimension auto Yes Yes The requested width of this component. 1.0

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).

Copied to clipboard.

{
  "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.

Name Type Default Description
command, commands Array of commands &mdash; An array of commands to run when this action is triggered.
enabled Boolean true When true, the user can invoke this action.
label String REQUIRED A localized description of this action for presentation to the user
name String REQUIRED The name of the action to perform

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.

Name Components Type Default event handler Description

activate

Touchable component

Explicit

onPress or onTap as a fallback if an onPress handler isn't provided.

Equivalent to a single press and release, or a single tap.

doubletap

Touchable component

Explicit

onDoublePress

Equivalent to double-tapping the component.

longpress

Touchable component

Explicit

onLongPress

Equivalent to long-press on a component.

scrollbackward

Implicit

None

Equivalent to scrolling the component one page backward. The scrolling action invokes any usual handlers that are invoked as a result of scrolling.

scrollforward

Implicit

None

Equivalent to scrolling component one page forward. The scrolling action invokes any usual handlers that are invoked as a result of scrolling.

swipeaway

Touchable component

Explicit

onSwipeDone

Equivalent to a swipe gesture on a component.

tap

Touchable component

Explicit

onTap property

Equivalent to a single tap.

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.

Copied to clipboard.

{
  "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.

Copied to clipboard.

{
  "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.

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.

Name Description
invisible The component isn't drawn, but takes up space. The component doesn't respond to touch events.
none Remove the component. The component isn't part of the layout and doesn't respond to touch.
normal Draw the component.

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:

Display Disabled Opacity Visible? Occupies Space? Focusable? Touchable? Touch and hover passes through?
normal false > 0 Yes Yes Yes Yes No
normal true > 0 Yes Yes No No No
normal false 0 No Yes Yes Yes No
normal true 0 No Yes No No No
invisible any any No Yes No No Yes
none any any No No No No Yes, but the component takes no space

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.

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:

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:

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.

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.

Type Description

sentence

Indicates a sentence element in the input text.

word

Indicates a word element in the text.

viseme

Describes the face and mouth movements corresponding to each phoneme in the speech.

ssml

Describes a <mark> element from the SSML input text.

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."

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.

The component layout model. The width and height properties set the bounds of the component. The padding properties inset the visible content of the component from the bounds.
The component layout model. The width and height properties set the bounds of the component. The padding properties inset the visible content of the component from the bounds.

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.

Array mapping Description

[X] expands to [X,X,X,X]

Assign the X value to all four sides.

[X,Y] expands to [X,Y,X,Y]

Assign the X value to both the left and right sides. Assign the Y value to the top and bottom.

[X,Y,Z] expands to [X,Y,Z,Y]

Assign the X value to the left side. Assign the Y value to the top and bottom. Assign the Z value to the right side.

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.

Property Left-to-right ("LTR") Right-to-left ("RTL")

paddingStart

Overrides paddingLeft

Overrides paddingRight

paddingEnd

Overrides paddingRight

Overrides paddingLeft

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:

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.

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:

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:

Property Group Type Default Description
rotate Rotate Number 0.0 Rotation angle, in degrees. Positive angles rotate in the clockwise direction.
scale Scale Number 1.0 Uniform scaling in both X and Y.
scaleX Scale Number 1.0 Scaling in the X direction (overrides "scale" if in same group)
scaleY Scale Number 1.0 Scaling in the Y direction (overrides "scale" if in same group)
skewX Skew Number 1.0 Skew angle for the X-axis, in degrees. X-axis lines remain horizontal.
skewY Skew Number 1.0 Skew angle for the Y-axis, in degrees. Y-axis lines remain vertical.
translateX Move Dimension 0.0 Distance to translate the object to the right.
translateY Move Dimension 0.0 Distance to translate the object down.

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:

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.


Was this page helpful?

Last updated: Feb 29, 2024