APL Frame

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

A Frame holds a single child and has a border and background color.

Properties

The Frame component has the following properties in addition to the base component properties. See the meaning of the columns.

Include height and width in your Frame definition.

Property	Type	Default	Styled	Dynamic	Description
`background`	Color or Gradient	—	Yes	Yes	Background fill that allows either a color or gradient. When you provide both `background` and `backgroundColor`, `background` is used.
`backgroundColor`	Color	—	Yes	Yes	Background color. Ignored if you provide both `backgroundColor` and `background`.
`borderBottomLeftRadius`	Non-negative Absolute Dimension	—	Yes	Yes	Radius of the bottom-left corner. Overrides `borderRadius`.
`borderBottomRightRadius`	Non-negative Absolute Dimension	—	Yes	Yes	Radius of the bottom-right corner. Overrides `borderRadius`.
`borderColor`	Color	—	Yes	Yes	Color of the border.
`borderRadius`	Non-negative Absolute Dimension	0	Yes	Yes	Corner radius for rounded-rectangle variant.
`borderStrokeWidth`	Non-negative Absolute Dimension	`borderWidth`	Yes	Yes	Width of the border stroke.
`borderTopLeftRadius`	Non-negative Absolute Dimension	—	Yes	Yes	Radius of the top-left corner. Overrides `borderRadius` if specified.
`borderTopRightRadius`	Non-negative Absolute Dimension	—	Yes	Yes	Radius of the top-right corner. Overrides `borderRadius` if specified.
`borderWidth`	Non-negative Absolute Dimension	0	Yes	Yes	Width of the border.
`item`, `items`	Array of components and layouts to display inside the `Frame`.	[]	No	No	Child component

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

{
  // Frame-specific values
  "type": "Frame",

  // General component values
  "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
  "uid": UID,          // Runtime-generated unique ID of the component
  "width": Number      // Width of the component, in dp (includes the padding)
}

background

The color or gradient to fill the background of the Frame. The background is drawn inside of the border.

The following example displays a box with a gradient background.

backgroundColor

Important: As of APL 2023.3, the backgroundColor property is deprecated. Use background instead. If both properties are specified, background is used and backgroundColor is ignored.

The color of the background. The background is drawn inside of the border.

borderRadius properties

Dimensional radii to apply against the border. Specify the radii in absolute dimensions. Relative dimensions aren't supported. Setting the border radii on a Frame doesn't clip the children of the frame.

The borderRadius property lets you set this value for all corners one time. You can override borderRadius for each corner of theFrame separately:

borderBottomLeftRadius
borderBottomRightRadius
borderTopLeftRadius
borderTopRightRadius

borderColor

The color of the border. Because the contents of a Frame are resized when the borderWidth changes (due to a style being applied), the borderWidth is frequently kept constant and the borderColor set to transparent (or backgroundColor) if a style needs to temporarily hide the border.

borderStrokeWidth

The width of the drawn border around the Frame. When not specified, borderStrokeWidth defaults to the specified borderWidth. When specified, the actual width of the drawn border is the smaller value of the borderStrokeWidth and borderWidth. You can't draw a border outside of the border width.

Set this property separately from borderWidth when you want to vary the width of the drawn border without re-laying out the positions of components in their parent. For example, assume you set borderWidth to 10 and borderStrokeWidth to 5. The component displays with a five-pixel border, but occupies enough space on the viewport for a ten-pixel border. When you change borderStrokeWidth to 10, the component displays with a ten-pixel border without changing the amount of space the component occupies.

In contrast, if you use borderWidth on its own and change it from 5 to 10, the components displayed on the screen shift to accommodate the larger border.

borderWidth

The width of the border. Specify the border width in absolute dimensions. Relative dimensions aren't supported. The border width doesn't affect the padding of the component. A drawn border is considered to be a background for the component and doesn't affect the component size or the positions of its children.

item, items

The child component or layout. If you provide more than one child item, only the first one selected by the when property is inflated.

Sample Frame

The following example creates a 100 x 100 circle with a Text item centered in the circle. The example uses the bindproperty to define a value for the width, height, and borderRadius properties. The example sets both background and backgroundColor. On a device with 2023.3 or later, the example uses the background property and displays a white to gray gradient background. On a device with an earlier version of APL, the example uses the backgroundColor property and displays a plain gray background.

For more examples of the Frame component, see Draw a border around items.

Was this page helpful?

Provide feedback

Last updated: Nov 28, 2023