APL Container (APL 1.6)


(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 Container component displays multiple child items. The Container uses a subset of Flexbox/Yoga as the layout language.

Properties

The Container component has the following properties:

Property Type Default Styled Dynamic Description

alignItems

One of: stretch, center, start, end, baseline

stretch

Yes

Yes

Alignment for children in the cross-axis.

direction

One of: column, row, columnReverse, rowReverse

column

Yes

Yes

Direction in which to display the child components.

justifyContent

One of: start, end, center, spaceBetween, spaceAround

start

Yes

Yes

How to distribute free space when there is room on the main axis. Defaults to start.

numbered

boolean

false

No

No

When true, assign ordinal numbers to children. Defaults to false.

wrap

One of: noWrap, wrap, wrapReverse

noWrap

Yes

Yes

Determines how to wrap child components to multiple lines.

Unlike standard Flexbox containers, The APL Container component doesn't scroll. Place the Container within a ScrollView to create a scrolling component.

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

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

  // 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)
}

alignItems

The Flexbox specification for how to align the child components in the cross-axis of the container. Defaults to stretch.

direction

The direction of layout in the container. Defaults to column. The direction property can take the following values:

Type Description

column

Lay out the child components in a vertical column (Default).

row

Lay out the child components in a horizontal row.

columnReverse

Lay out the child components in a vertical column, but start from the opposite side

rowReverse

Lay out the child components in a horizontal row , but start from the opposite side

justifyContent

The Flexbox specification for how to distribute free space when there is room on the main axis. This property applies when the container is larger than the size of its children. Defaults to start.

numbered

When true, set the data-binding ordinal for each of the items in the Container. The ordinals start with "1" and increment by one unless the numbering property in a child is set to "skip" or "reset". Note that the firstItem and lastItem properties don't participate in ordinal numbering. Defaults to false.

wrap

The Flexbox wrapping behavior of the children. The wrap property takes the following values:

Type Description

noWrap

The Container lays out the children in a single line on the main axis. The Container might overflow. (Default)

wrap

The child components can break into multiple lines.

wrapReverse

The child components can break into multiple lines, but start from the opposite side.

Multichild properties

A Container is a multi-child component. The Container inherits all of the multi-child properties.

Container child component properties

The child components of a Container have additional properties to control positioning within the parent container.

Property Type Default Styled Dynamic Description

alignSelf

auto, start, end, center, baseline, stretch

auto

Yes

Yes

Cross-axis layout position. Defaults to auto.

bottom

Dimension

none

Yes

Yes

Specifies the position offset of the bottom edge.

grow

Number

0

Yes

Yes

When positive, proportionally stretch this component if there is extra space in the Container. Defaults to 0.

left

Dimension

none

Yes

Yes

Specifies the position offset of the left edge.

numbering

normal, skip, reset

normal

No

No

Control ordinal numbering of the next child. Defaults to normal.

position

relative, absolute

relative

Yes

Yes

When absolute, take this component out of the normal layout ordering and position it relative to the parent container. Defaults to 'relative'.

right

Dimension

none

Yes

Yes

Specifies the position offset of the right edge.

shrink

Number

0

Yes

Yes

When positive, proportionally shrink this component if there is not enough space in the Container. Defaults to 0.

spacing

Absolute Dimension

0

Yes

Yes

Additional space to add between this component and the previous component in the layout. Defaults to 0.

top

Dimension

none

Yes

Yes

Specifies the position offset of the top edge.

alignSelf

Overrides the alignItems property for this child component.

position, bottom, left, right, top

The position property determines how the bottom, left, right, and top properties adjust the position of the child component from its "standard" location.

When position is absolute, the child component is taken out of the normal layout ordering for the container and instead positioned absolutely relative to the parent. The top, bottom, left, and right properties are dimensional offsets from the sides of the parent container. The padding of the parent container is ignored for an absolutely positioned child component.

In an "absolute"-positioned element where the size of the element is fixed, the left property overrides the right property when both are set and the top property overrides the bottom property when both are set. When none of bottom, left, right, or top have a value, the child component is positioned at the top-left of the parent container.

The following example shows a component positioned 5 units from the top-right of its parent container.

{
  "position": "absolute",
  "width": 100,
  "height": 100,
  "top": 5,
  "bottom": 5, // Ignored because "top" was set
  "right": 5
}

When position is relative, the bottom, left, right, and top properties are dimensional offsets from the "normal" position of the child. When top has a value, the bottom property is ignored. When left has a value, the right property is ignored.

For example, the following component will be positioned 5 units down and 5 units to the left of its "normal" position:

{
  "position": "relative",
  "top": 5,
  "bottom": 20,    // Ignored because "top" was set
  "right": 5
}

grow, shrink

Flexbox grow and shrink properties. A positive grow value stretches the component proportionally when there is extra space in the container. A positive shrink value allows the component to shrink below its normal size when there is not enough space in the container.

Negative grow or shrink values are ignored.

numbering

Controls the ordinal value when the parent has set numbered. This property controls how the ordinal value updates for the next child in the sequence, not the current child in the sequence.

  • normal: The next child's ordinal = ordinal + 1.
  • skip: The next child's ordinal = ordinal
  • reset: The next child's ordinal = 1

spacing

An amount of spacing to add between this component and the previous child component in the layout. The first item in the layout ignores spacing. Specify the spacing in absolute dimensions. The spacing property doesn't support relative dimensions.

The spacing properties applies to child components where position is relative. The property is ignored for child components where position is absolute.


Was this page helpful?

Last updated: Nov 28, 2023