Skip to main content

Layout Engine

The Layout Engine automatically arranges elements within containers, making it easy to create responsive layouts without manual positioning.

Vertical Stack Container​

A Vertical Stack Container is a special type of container that automatically arranges its child elements vertically, one after another. This eliminates the need to manually calculate positions for each element.

How It Works​

When you mark a container as a vertical stack container, it will:

  • Automatically position child elements from top to bottom
  • Respect the order defined by displayOrder
  • Apply padding and margins consistently
  • Adjust container height automatically based on its children
┌─────────────────────────────────┐
│ Container (isVerticalStackContainer: true)
│ ┌─────────────────────────────┐ │
│ │ paddingTop                  │ │
│ ├─────────────────────────────┤ │
│ │ Child 1 (Text)              │ │
│ │ marginBottom: 10            │ │
│ ├─────────────────────────────┤ │
│ │ Child 2 (Text)              │ │
│ │ marginBottom: 10            │ │
│ ├─────────────────────────────┤ │
│ │ Child 3 (Text)              │ │
│ ├─────────────────────────────┤ │
│ │ paddingBottom               │ │
│ └─────────────────────────────┘ │
└─────────────────────────────────┘

Why Use Vertical Stack Containers?​

Benefits:

  • Dynamic Layout: Container height adjusts automatically when content changes
  • Consistent Spacing: Margins and padding are applied uniformly
  • Easy Maintenance: Add or remove elements without recalculating positions
  • Responsive Design: Elements automatically adapt to container width

Use Cases:

  • Card layouts with multiple text elements
  • Lists of items that need consistent spacing
  • Content sections that grow dynamically
  • Any layout where elements should stack vertically

Container Properties​

interface Container {
  isVerticalStackContainer: boolean;
  containerLayout: {
    paddingLeft: number;    // default: 10
    paddingRight: number;   // default: 10
    paddingTop: number;     // default: 10
    paddingBottom: number;  // default: 10
    growDirection: 'top' | 'bottom';  // default: 'bottom'
  };
}

Padding​

Padding controls the space between the container's border and its children:

  • paddingTop / paddingBottom: Vertical spacing
  • paddingLeft / paddingRight: Horizontal spacing

Grow Direction​

The growDirection property controls where new content is added and how the container expands. This is especially important when the container's position is fixed and you want to control which side stays anchored.

'bottom' (Default)​

When growDirection is 'bottom', the container grows downward. The top edge stays fixed, and new elements are added below existing ones:

Initial State:
┌─────────────────────┐
│ Container           │
│ ┌─────────────────┐ │
│ │ Child 1         │ │ ← Top edge (fixed)
│ │ Child 2         │ │
│ └─────────────────┘ │
└─────────────────────┘

After adding Child 3:
┌─────────────────────┐
│ Container           │
│ ┌─────────────────┐ │
│ │ Child 1         │ │ ← Top edge (still fixed)
│ │ Child 2         │ │
│ │ Child 3         │ │ ← New element added below
│ └─────────────────┘ │
└─────────────────────┘
     ↓ Container grows downward

Use 'bottom' when:

  • The container is positioned at the top of the canvas
  • You want the top edge to stay in place
  • Content should flow downward naturally
  • This is the most common use case

'top'​

When growDirection is 'top', the container grows upward. The bottom edge stays fixed, and new elements are added above existing ones:

Initial State:
┌─────────────────────┐
│ Container           │
│ ┌─────────────────┐ │
│ │ Child 1         │ │
│ │ Child 2         │ │
│ └─────────────────┘ │
│                      │ ← Bottom edge (fixed)
└─────────────────────┘

After adding Child 3:
┌─────────────────────┐
│ Container           │
│ ┌─────────────────┐ │
│ │ Child 3         │ │ ← New element added above
│ │ Child 1         │ │
│ │ Child 2         │ │
│ └─────────────────┘ │
│                      │ ← Bottom edge (still fixed)
└─────────────────────┘
     ↑ Container grows upward

Use 'top' when:

  • The container is positioned at the bottom of the canvas
  • You want the bottom edge to stay in place
  • Content should flow upward (e.g., chat messages, notifications)
  • The container is anchored to the bottom of the design

Visual Comparison​

growDirection: 'bottom'          growDirection: 'top'
┌─────────────────────┐         ┌─────────────────────┐
│ Container           │         │ Container           │
│ ┌─────────────────┐ │         │ ┌─────────────────┐ │
│ │ Child 1        │ │ ← Fixed │ │ Child 3        │ │ ← Grows up
│ │ Child 2        │ │         │ │ Child 1        │ │
│ │ Child 3        │ │ ↓ Grows │ │ Child 2        │ │
│ └─────────────────┘ │         │ └─────────────────┘ │
│                      │         │                      │ ← Fixed
└─────────────────────┘         └─────────────────────┘

Child Layout​

Children of a vertical stack container can have margins to control spacing:

{
  parentContainerId: "container-id",
  childLayout: {
    marginTop: 0,
    marginBottom: 10,    // Space after this element
    marginLeft: 0,
    marginRight: 0
  }
}

The marginBottom property is particularly useful for creating consistent spacing between stacked elements.

See also​