Stack

A layout utility that manages spacing and alignment of its immediate children along a single vertical or horizontal axis.

One

Two

Three

Usage

forge-stack lays out its immediate children along one axis through inline (horizontal instead of the default vertical), wrap, stretch, gap, alignment, and justify. It’s a thin, single-purpose abstraction over flex — reach for CSS Flexbox or Grid directly once a layout needs more than one axis or more complex behavior than the stack’s own properties cover.

It’s easy to overuse the stack component and end up with a lot of nested stacks, which hurts both performance and maintainability. Use it judiciously — for straightforward single-axis spacing — and reach for CSS Flexbox or Grid for anything more complex.

Rules

Use a stack for simple, single-axis spacing between a handful of children.

Set gap to a Forge spacing token instead of margins on individual children.

Reach for CSS Flexbox or Grid once a layout needs more than one axis.

Don't

Don't nest more than a couple of stacks to build a complex layout — that's a sign to switch to Flexbox or Grid directly.

Don't use a stack as a general-purpose container — it's a spacing utility, not a layout component with its own semantics.

Basic usage

Children stack vertically by default, spaced by gap.

A vertical stack with even spacing between children.

<div class="stack-container">
  <forge-stack gap="16">
    <div class="border-thick border-dotted border-outline-medium bg-surface-container-low rounded-lg h-[25px] w-[25px]">
    </div>
    <div class="border-thick border-dotted border-outline-medium bg-surface-container-low rounded-lg h-[75px] w-[75px]">
    </div>
    <div class="border-thick border-dotted border-outline-medium bg-surface-container-low rounded-lg h-[100px] w-[100px]">
    </div>
    <div class="border-thick border-dotted border-outline-medium bg-surface-container-low rounded-lg h-[125px] w-[125px]">
    </div>
  </forge-stack>
</div>

Vertical form

A vertical stack keeps form fields evenly spaced without hand-tuned margins between them.

A simple vertical form layout with even spacing between fields.

<form>
  <forge-stack gap="16">
    <forge-text-field>
      <label for="input-text-1" slot="label">
        Text field
      </label>
      <input type="text" id="input-text-1">
    </forge-text-field>
    <forge-text-field>
      <label for="input-text-2" slot="label">
        Text field
      </label>
      <input type="text" id="input-text-2">
    </forge-text-field>
    <forge-text-field>
      <label for="input-text-3" slot="label">
        Text field
      </label>
      <input type="text" id="input-text-3">
    </forge-text-field>
    <forge-text-field>
      <label for="input-text-4" slot="label">
        Text field
      </label>
      <input type="text" id="input-text-4">
    </forge-text-field>
    <forge-text-field>
      <label for="input-text-5" slot="label">
        Text field
      </label>
      <input type="text" id="input-text-5">
    </forge-text-field>
  </forge-stack>
</form>

Nesting for multi-column layouts

Nest an inline stack inside a vertical one for a form with multiple columns or mixed spacing — keep nesting shallow, since this is exactly the pattern that gets unwieldy if it grows much further.

A more complex form layout using nested stacks for multiple columns.

<form>
  <forge-stack>
    <forge-stack>
      <forge-stack>
        <forge-text-field>
          <label for="input-text-1" slot="label">
            Text field
          </label>
          <input type="text" id="input-text-1">
        </forge-text-field>
        <forge-stack inline stretch>
          <forge-text-field>
            <label for="input-text-2" slot="label">
              Text field
            </label>
            <input type="text" id="input-text-2">
          </forge-text-field>
          <forge-text-field>
            <label for="input-text-3" slot="label">
              Text field
            </label>
            <input type="text" id="input-text-3">
          </forge-text-field>
        </forge-stack>
      </forge-stack>
      <forge-stack inline stretch>
        <forge-stack inline stretch>
          <forge-text-field>
            <input type="text" id="input-text-4">
            <label for="input-text-4" slot="label">
              Text field
            </label>
          </forge-text-field>
          <forge-text-field>
            <input type="text" id="input-text-5">
            <label for="input-text-5" slot="label">
              Text field
            </label>
          </forge-text-field>
        </forge-stack>
        <forge-stack inline stretch>
          <forge-text-field>
            <input type="text" id="input-text-6">
            <label for="input-text-6" slot="label">
              Text field
            </label>
          </forge-text-field>
        </forge-stack>
      </forge-stack>
    </forge-stack>
  </forge-stack>
</form>

The stack is a utility component that helps manage spacing and alignment of immediate children along a vertical or horizontal axis. Use stacks sparingly to avoid unnecessary DOM complexity, and prefer CSS flexbox or grid for more complex layouts.

import "@tylertech/forge/stack";

Properties

Property	Attribute	Type	Default	Description
`inline`	`inline`	`boolean`	`false`	Controls the direction of the stack.
`wrap`	`wrap`	`boolean`	`false`	Controls if items wrap to a new line in inline mode
`stretch`	`stretch`	`boolean`	`false`	Controls if items stretch and take up the maximum amount of space
`gap`	`gap`	`StackGapSize \| (string & {})`	`"16"`	Controls the gap between the children within the stack. Accepts a CSS length, a unitless pixel number, or a spacing token size (`xxxs`, `xxs`, `xs`, `s`, `m`, `ml`, `l`, `xl`, `xxl`, `xxxl`) which maps to `--forge-spacing-*`.
`alignment`	`alignment`	`StackAlignment`	`"start"`	Controls the align-items property of a row or column
`justify`	`justify`	`StackAlignment`	`"start"`	Controls the justify-content property of a row or column

Slots

Name	Description
`(default)`	The default/unnamed slot for stack content.

CSS Parts

Name	Description
`::part(root)`	The root container element.

CSS Custom Properties

Name	Description
`--forge-stack-alignment`	Controls the align-items CSS property of the root stack element.
`--forge-stack-justify`	Controls the justify-content CSS property of the root stack element.
`--forge-stack-gap`	Controls the gap between each child element within a stack.
`--forge-stack-height`	Controls the height of the root stack element.
`--forge-stack-stretch`	Controls the flex shorthand property of a child element within the stack.

Accessibility documentation coming soon.