# StackLayout
```js
const { StackLayout } = require('sketch/dom')
```

Describes a particular [Stack Layout](https://www.sketch.com/docs/designing/stack-layout/).

| Properties |  |
| --- | --- |
| direction<span class="arg-type">[StackLayout.Direction](#stacklayoutdirection)</span> | Defines how the stack is laid out |
| justifyContent<span class="arg-type">[StackLayout.JustifyContent](#stacklayoutjustifycontent)</span> | Defines the alignment of content along the main axis of a stack. `justify-content` in CSS |
| alignItems<span class="arg-type">[StackLayout.AlignItems](#stacklayoutalignitems)</span> | Defines the alignment of content on the stack's cross-axis. `align-items` in CSS |
| gap<span class="arg-type">number</span> | A gap between individual stack items |
| padding<span class="arg-type">object / number </span> | The stack's padding around its content. When set to a number, denotes uniform padding for all edges |
| padding.vertical, padding.horizontal | Sets padding per axis: `vertical` for top and bottom, `horizontal` for left and right |
| padding.top, padding.left, padding.bottom, padding.right | Sets padding per individual edge |

| Wrapping Properties |  |
| --- | --- |
| wraps<span class="arg-type">boolean</span> | Whether the contents of the stack should wrap when their combined _height_ (for vertical stacks) or _width_ (for horizontal stacks) exceeds the stack's fixed dimensions |
| alignContent<span class="arg-type">[StackLayout.JustifyContent](#stacklayoutjustifycontent)</span> | Defines how the wrapped content should be aligned on the cross axis of the stack |
| crossAxisGap<span class="arg-type">number</span> | A gap between wrapped lines of the stack |

## Inspecting Stacks

```js
if (group.stackLayout) {
  // This is a Stack
}
```

Use the `stackLayout` property of a [`Group`](#Group) to find out whether a given container is a stack.

```js
const { direction, alignItems, ...other } = group.stackLayout

if (group.stackLayout.justifyContent === StackLayout.JustifyContent.End) {
  // ...
}
```

Inspect this property further to learn more about that particular stack:

## Creating Stacks

```js
const stack = new Group({
  stackLayout: {
    direction: StackLayout.Direction.Column,
    alignItems: StackLayout.AlignItems.Center,
    gap: 120,
  },
  layers: [
    /* ... */
  ],
})
```

To create a brand new container with a Stack Layout, pass a `stackLayout` object to a `Group` constructor:

## Converting containers to Stacks

```js
const group = new Group.Frame(/* ... */)

group.stackLayout = {
  padding: { top: 50, bottom: 30 },
}
```

In order to turn an existing layer group to a stack, assign a layout object to its `stackLayout` property:

## Updating Stacks

```js
const stack = new Group({
  stackLayout: { padding: 10 },
  layers: [
    /* ... */
  ],
})

stack.layers.push(new Text(/* ... */))
stack.stackLayout.apply()
```

After adding or removing layers from a stack, call `StackLayout.apply()` to update the layout:

```js
stack.layers[0].ignoresStackLayout = true

const stack = new Group({
  stackLayout: { padding: 10 },
  layers: [
    new Text({
      preservesSpaceInStackLayoutWhenHidden: true,
    }),
  ],
})
```

Once added to a stack, layers gain additional layout properties:

| Property | Description |
| --- | --- |
| `ignoresStackLayout`<span class="arg-type">boolean</span> | Controls whether this layer ignores the enclosing Stack Layout properties when positioning itself |
| `preservesSpaceInStackLayoutWhenHidden`<span class="arg-type">boolean</span> | Controls whether a Stack should keep a layer's space even when it's hidden |

## Wrapping Stacks

```js
const { Group, StackLayout, FlexSizing } = require('sketch')

// for new Stacks
const stack = new Group.Frame({
  stackLayout: {
    direction: StackLayout.Direction.Row,
    wraps: true,
  },
  horizontalSizing: FlexSizing.Fixed,
})

// or, for existing Stacks
container.stackLayout.wraps = true
```

Use `StackLayout.wrap` property to control whether the contents of a particular Stack Layout should wrap when their combined _height_ (for vertical stacks) or _width_ (for horizontal stacks) exceeds the Stack's fixed dimensions:

```js
container.stackLayout.alignContent = StackLayout.AlignContent.End
```

You can also choose how the wrapped content should be aligned on the cross axis:

```js
container.stackLayout.crossAxisGap = 30
```

And specify an optional gap between wrapped lines:

## Removing Stack Layout from containers

```js
container.stackLayout = null
```

Set the `stackLayout` value to `null` to remove the Stack Layout from the given stack and effectively convert it to a regular layer container.

## `StackLayout.Direction`

| Value    | Description                    |
| -------- | ------------------------------ |
| `Row`    | Lay out the stack horizontally |
| `Column` | Lay out the stack vertically   |

## `StackLayout.JustifyContent`

| Value | Description |
| --- | --- |
| `Start` | Lay out from the start of the stack (e.g. left or top) |
| `Center` | Center items within the stack |
| `End` | Lay out from the end of the stack (e.g. right or bottom) |
| `Between` | Add spacing _between_ the items so the stack is filled. `space-between` in CSS. |
| `Around` | Add spacing either side of every item so the stack is filled. Visually the spacing at start and end of the stack is half of the other spaces, because there's only a single item to add spacing to `space-around` in CSS. |
| `Evenly` | Add spacing between every item _and_ at the start and end of the stack. `space-evenly` in CSS. |

## `StackLayout.AlignItems`

| Value | Description |
| --- | --- |
| `Start` | Align to the start of the cross-axis (e.g. left or top) |
| `Center` | Align to the center of the cross-axis |
| `End` | Align to the end of the cross-axis (e.g. right or bottom). |
| `Stretch` | Align items by stretching. |
| `None` | For an individual stack item, use the default alignment inherited from the stack |