Stack

Stack is the fundamental layout container that organizes child elements in configurable horizontal or vertical arrangements. As the most versatile building block in XMLUI's layout system, it provides comprehensive alignment, spacing, and flow control options that serve as the foundation for all specialized stack variants.

Key features:

Dynamic orientation: Switch between horizontal and vertical layouts programmatically
Comprehensive alignment: Precise control over both horizontal and vertical child positioning
Flexible spacing: Configurable gaps between elements with theme-aware sizing
Content wrapping: Automatic wrapping when space constraints require it
Order control: Reverse child element order with the reverse property
Foundation for variants: Powers HStack, VStack, CHStack, and CVStack specialized components

For common scenarios, consider the specialized variants: HStack (horizontal), VStack (vertical), CHStack (centered horizontal), and CVStack (centered vertical).

Behaviors

This component supports the following behaviors:

Behavior	Properties
Animation	`animation`, `animationOptions`
Bookmark	`bookmark`, `bookmarkLevel`, `bookmarkTitle`, `bookmarkOmitFromToc`
Component Label	`label`, `labelPosition`, `labelWidth`, `labelBreak`, `required`, `enabled`, `shrinkToLabel`, `style`, `readOnly`
Publish/Subscribe	`subscribeToTopic`
Tooltip	`tooltip`, `tooltipMarkdown`, `tooltipOptions`
Styling Variant	`variant`

Properties

`gap`

default: "$gap-normal"

Optional size value indicating the gap between child elements.

In the following example we use pixels, characters (shorthand ch), and the em CSS unit size which is a relative size to the font size of the element (See size values).

<App>
  <Stack orientation="horizontal" backgroundColor="cyan"
    gap="80px">
    <Stack height="40px" width="40px" backgroundColor="red" />
    <Stack height="40px" width="40px" backgroundColor="green" />
    <Stack height="40px" width="40px" backgroundColor="blue" />
    <Stack height="40px" width="40px" backgroundColor="yellow" />
  </Stack>
  <Stack orientation="horizontal" backgroundColor="cyan"
    gap="12ch">
    <Stack height="40px" width="40px" backgroundColor="red" />
    <Stack height="40px" width="40px" backgroundColor="green" />
    <Stack height="40px" width="40px" backgroundColor="blue" />
    <Stack height="40px" width="40px" backgroundColor="yellow" />
  </Stack>
</App>

Example: gap

<App>
  <Stack orientation="horizontal" backgroundColor="cyan"
    gap="80px">
    <Stack height="40px" width="40px" backgroundColor="red" />
    <Stack height="40px" width="40px" backgroundColor="green" />
    <Stack height="40px" width="40px" backgroundColor="blue" />
    <Stack height="40px" width="40px" backgroundColor="yellow" />
  </Stack>
  <Stack orientation="horizontal" backgroundColor="cyan"
    gap="12ch">
    <Stack height="40px" width="40px" backgroundColor="red" />
    <Stack height="40px" width="40px" backgroundColor="green" />
    <Stack height="40px" width="40px" backgroundColor="blue" />
    <Stack height="40px" width="40px" backgroundColor="yellow" />
  </Stack>
</App>

`horizontalAlignment`

default: "start"

Manages the horizontal content alignment for each child element in the Stack.

Available values: start (default), center, end

The start and end values can be affected by i18n if the layout is in a right-to-left writing style.

<App>
  <Stack width="100%" horizontalAlignment="center" backgroundColor="cyan">
    <Stack width="36px" height="36px" backgroundColor="red" />
  </Stack>
</App>

Example: horizontalAlignment

<App>
  <Stack width="100%" horizontalAlignment="center" backgroundColor="cyan">
    <Stack width="36px" height="36px" backgroundColor="red" />
  </Stack>
</App>

`itemWidth`

The default width applied to child elements in the Stack. For vertical stacks, defaults to '100%' (children take full width). For horizontal stacks, defaults to 'fit-content' (children size to their content).

`orientation`

default: "vertical"

An optional property that governs the Stack's orientation (whether the Stack lays out its children in a row or a column).

Available values: horizontal, vertical (default)

`reverse`

default: false

Optional boolean property to reverse the order of child elements.

Default is false, which indicates a left-to-right layout.

<App>
  <Stack backgroundColor="cyan">
    <Stack gap="10px" orientation="horizontal">
      <Stack height="40px" width="40px" backgroundColor="red" />
      <Stack height="40px" width="40px" backgroundColor="green" />
      <Stack height="40px" width="40px" backgroundColor="blue" />
    </Stack>
    <Stack reverse="true" orientation="horizontal">
      <Stack height="40px" width="40px" backgroundColor="red" />
      <Stack height="40px" width="40px" backgroundColor="green" />
      <Stack height="40px" width="40px" backgroundColor="blue" />
    </Stack>
  </Stack>
</App>

Example: reverse

<App>
  <Stack backgroundColor="cyan">
    <Stack gap="10px" orientation="horizontal">
      <Stack height="40px" width="40px" backgroundColor="red" />
      <Stack height="40px" width="40px" backgroundColor="green" />
      <Stack height="40px" width="40px" backgroundColor="blue" />
    </Stack>
    <Stack reverse="true" orientation="horizontal">
      <Stack height="40px" width="40px" backgroundColor="red" />
      <Stack height="40px" width="40px" backgroundColor="green" />
      <Stack height="40px" width="40px" backgroundColor="blue" />
    </Stack>
  </Stack>
</App>

`scrollStyle`

default: "normal"

This property determines the scrollbar style. Options: "normal" uses the browser's default scrollbar; "overlay" displays a themed scrollbar that is always visible; "whenMouseOver" shows the scrollbar only when hovering over the scroll container; "whenScrolling" displays the scrollbar only while scrolling is active and fades out after 400ms of inactivity.

Available values: normal (default), overlay, whenMouseOver, whenScrolling

`showScrollerFade`

default: true

When enabled, displays gradient fade indicators at the top and bottom of the scroll container to visually indicate that more content is available in those directions. The fade indicators automatically appear/disappear based on the current scroll position. Top fade shows when scrolled down from the top, bottom fade shows when not at the bottom. Only works with overlay scrollbar modes (not with 'normal' mode).

`verticalAlignment`

default: "start"

Manages the vertical content alignment for each child element in the Stack.

Available values: start (default), center, end

<App>
  <Stack height="100px" verticalAlignment="end" backgroundColor="cyan">
    <Stack width="36px" height="36px" backgroundColor="red" />
  </Stack>
</App>

Example: verticalAlignment

<App>
  <Stack height="100px" verticalAlignment="end" backgroundColor="cyan">
    <Stack width="36px" height="36px" backgroundColor="red" />
  </Stack>
</App>

`wrapContent`

default: false

Optional boolean which wraps the content if set to true and the available space is not big enough. Works only with horizontal orientations.

Optional boolean which wraps the content if set to true and the available space is not big enough. Works in all orientations.

<App>
  <Stack wrapContent="true" width="140px" orientation="horizontal" backgroundColor="cyan">
    <Stack height="40px" width="40px" backgroundColor="blue" />
    <Stack height="40px" width="40px" backgroundColor="blue" />
    <Stack height="40px" width="40px" backgroundColor="blue" />
    <Stack height="40px" width="40px" backgroundColor="blue" />
  </Stack>
</App>

Example: wrapContent

<App>
  <Stack wrapContent="true" width="140px" orientation="horizontal" backgroundColor="cyan">
    <Stack height="40px" width="40px" backgroundColor="blue" />
    <Stack height="40px" width="40px" backgroundColor="blue" />
    <Stack height="40px" width="40px" backgroundColor="blue" />
    <Stack height="40px" width="40px" backgroundColor="blue" />
  </Stack>
</App>

Events

`click`

This event is triggered when the Stack is clicked.

Signature: click(event: MouseEvent): void

event: The mouse event object.

Describes the logic that fires when the component is clicked.

<App>
  <HStack var.shown="{false}">
    <Stack height="40px" width="40px" backgroundColor="red" onClick="shown = !shown" />
    <Stack when="{shown}" height="40px" width="40px" backgroundColor="blue" />
  </HStack>
</App>

Example: click

<App>
  <HStack var.shown="{false}">
    <Stack height="40px" width="40px" backgroundColor="red" onClick="shown = !shown" />
    <Stack when="{shown}" height="40px" width="40px" backgroundColor="blue" />
  </HStack>
</App>

`contextMenu`

This event is triggered when the Stack is right-clicked (context menu).

Signature: contextMenu(event: MouseEvent): void

event: The mouse event object.

Exposed Methods

`scrollToBottom`

Scrolls the Stack container to the bottom. Works when the Stack has an explicit height and overflowY is set to 'scroll'.

Signature: scrollToBottom(behavior?: 'auto' | 'instant' | 'smooth'): void

`scrollToEnd`

Scrolls the Stack container to the end (right in LTR, left in RTL). Works when the Stack has an explicit width and overflowX is set to 'scroll'.

Signature: scrollToEnd(behavior?: 'auto' | 'instant' | 'smooth'): void

`scrollToStart`

Scrolls the Stack container to the start (left in LTR, right in RTL). Works when the Stack has an explicit width and overflowX is set to 'scroll'.

Signature: scrollToStart(behavior?: 'auto' | 'instant' | 'smooth'): void

`scrollToTop`

Scrolls the Stack container to the top. Works when the Stack has an explicit height and overflowY is set to 'scroll'.

Signature: scrollToTop(behavior?: 'auto' | 'instant' | 'smooth'): void

Styling

Theme Variables

Variable	Default Value (Light)	Default Value (Dark)
gap-Stack	$gap-normal	$gap-normal