APL Base Component Properties (APL 1.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 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 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

The standard properties in a component are as follows. In general, any property related to dimensions cannot be used to provide padding for components.

Property	Type	Required	Styled	Dynamic	Description
`bind`	Array of bindings	No	No	No	Expressions to add to the data binding context.
`entity` (`entities`)	Array of entities	No	No	No	Opaque data used to clarify references in Alexa.
`height`	Dimension	No	No	Read-only	Requested height of the component. Defaults to `auto`.
`id`	String	No	No	No	Reference name of the component, used for navigation and events. Required if the component is used with standard built-in intents.
`inheritParentState`	Boolean	No	No	No	If true, use the parent's state.
`maxHeight`	Dimension	No	No	No	Maximum allowed height of this component. Defaults to `none`.
`maxWidth`	Dimension	No	No	No	Maximum allowed width of this component. Defaults to `none`.
`minHeight`	Dimension	No	No	No	Minimum allowed height of this component. Defaults to 0.
`minWidth`	Dimension	No	No	No	Minimum allowed width of this component. Defaults to 0.
`paddingBottom`	Dimension: Properties	No	No	No	Space to add to the bottom of this component. Defaults to 0.
`paddingLeft`	Dimension: Properties	No	No	No	Space to add to the left of this component. Defaults to 0.
`paddingRight`	Dimension: Properties	No	No	No	Space to add to the right of this component. Defaults to 0.
`paddingTop`	Dimension: Properties	No	No	No	Space to add to the top of this component. Defaults to 0.
`style`	Style	No	No	No	Named style or styles to apply.
`type`	String	Yes	No	No	Type of the component. Required.
`when`	Boolean	No	No	No	If the expression with `when` evaluates to `false`, this component is not inflated or selected. Defaults to `true`.
`width`	Dimension: Properties	No	No	Read-only	Requested width of this component. Defaults to `auto`.

bind

The bind property of a component extends the data-binding context for the component and its children. The bind property also specifies an ordered set of data-bindings that extend the current context. Bindings are ordered, and later bindings may use previous definitions.

bind properties

Each binding object in the binding array contains the following properties

Property	Type	Required	Description
`name`	String	Yes	Name to use for this binding. Must be a valid name.
`value`	Any	Yes	Value to assign to this binding. If a string, data-binding will occur on the contents of the string.
`type`	Type	No	Property type. Defaults to `any`.

bind evaluation

The bind property evaluates after the when property and before any other properties. In other words, the when expression cannot rely on the new bindings, but other properties of this component may rely on the bindings. For example:

{
"type": "Text",
"bind": [
{ "name": "foo", "value": "27" },
{ "name": "bar", "value": "${foo + 23}" }
],
"text": "The value of bar is ${bar}"
}

In this example, foo and bar augment the data-binding context. The final text will be "The value of bar is 2723" because the addition of a string and an integer results in an implicit cast to string.

entity

Opaque entity data. Alexa devices pass the entity data back to the skill as context.

height and width

The properties width, height, minWidth, minHeight, maxWidth, and maxHeight are dimensional properties.

Minimum width and height values default to 0, which means the component can disappear. Maximum width and height properties default to none, which indicates that the component can scale arbitrarily. If unspecified, the width and height values will revert to the component's natural size.

id

A developer-assigned value used to locate a particular component in the view hierarchy. Although recommended, the id is not required to be unique.

inheritParentState

Replaces the component state with the state of the parent of the component. Used for components that need to visually change appearance based on the state of the parent. For example, you may want a Text component inside of a TouchWrapper to change color when the TouchWrapper is pressed. By setting inheritParentState, the Text component will change state whenever the TouchWrapper changes state.

paddingBottom, paddingLeft, paddingRight, and paddingTop

Padding values are dimensions that add space around a component. APL uses the border-box model for calculating the total width and height of an element. Default for each is 0.

style

The style is a named style. If no style is assigned, the component will use a platform-defined internal style.

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.

Last updated: Feb 07, 2023