# Stack

The Stack component creates a vertical layout of elements with consistent
spacing between them. It's one of the fundamental layout components in Atlantis
that helps create clean, organized interfaces.

The Stack differs from our legacy Content component in that it's not tackling
multiple use cases. The Stack only manages vertical spacing between elements.
Content also managed the padding around the edges of the content, which is now
handled by Box. Splitting the two components allows them both to be more
flexible and useful than before.

## When to use

Use Stack when you need to:

* Create vertical layouts with consistent spacing
* Build forms with evenly spaced fields
* Layout content in cards or modals
* Create sections with equal vertical rhythm

## Examples

### Basic Stack

```tsx
import React from "react";
import { Stack } from "@jobber/components/Stack";
import { Card } from "@jobber/components/Card";
import { Box } from "@jobber/components/Box";
import { Text } from "@jobber/components/Text";

export function StackBasicExample() {
  return (
    <Stack gap="base">
      <Card>
        <Box padding="base">
          <Text>First item</Text>
        </Box>
      </Card>
      <Card>
        <Box padding="base">
          <Text>Second item</Text>
        </Box>
      </Card>
      <Card>
        <Box padding="base">
          <Text>Third item</Text>
        </Box>
      </Card>
    </Stack>
  );
}
```

### Custom Spacing

```tsx
import React from "react";
import { Stack } from "@jobber/components/Stack";
import { Card } from "@jobber/components/Card";
import { Box } from "@jobber/components/Box";
import { Text } from "@jobber/components/Text";

export function StackCustomSpacingExample() {
  return (
    <Stack gap="large">
      <Card>
        <Box padding="base">
          <Text>First item</Text>
        </Box>
      </Card>
      <Card>
        <Box padding="base">
          <Text>Second item</Text>
        </Box>
      </Card>
      <Card>
        <Box padding="base">
          <Text>Third item</Text>
        </Box>
      </Card>
    </Stack>
  );
}
```

### Split Layout

```tsx
import React from "react";
import { Stack } from "@jobber/components/Stack";
import { Card } from "@jobber/components/Card";
import { Box } from "@jobber/components/Box";
import { Text } from "@jobber/components/Text";

export function StackWithSplitExample() {
  return (
    <div style={{ height: "400px" }}>
      <Stack gap="base" splitAfter={1}>
        <Card>
          <Box padding="base">
            <Text>First item</Text>
          </Box>
        </Card>
        <Card>
          <Box padding="base">
            <Text>Second item</Text>
          </Box>
        </Card>
        <Card>
          <Box padding="base">
            <Text>Third item</Text>
          </Box>
        </Card>
      </Stack>
    </div>
  );
}
```

### Recursive Spacing

```tsx
import React from "react";
import { Stack } from "@jobber/components/Stack";
import { Card } from "@jobber/components/Card";
import { Box } from "@jobber/components/Box";
import { Text } from "@jobber/components/Text";

export function StackRecursiveExample() {
  return (
    <Stack gap="large" recursive>
      <Box>
        <Card>
          <Box padding="base">
            <Text>Nested item 1.1</Text>
            <Text>Nested item 1.1.2</Text>
          </Box>
        </Card>
        <Card>
          <Box padding="base">
            <Text>Nested item 1.2</Text>
          </Box>
        </Card>
      </Box>
      <Box>
        <Card>
          <Box padding="base">
            <Text>Nested item 2.1</Text>
          </Box>
        </Card>
        <Card>
          <Box padding="base">
            <Text>Nested item 2.2</Text>
          </Box>
        </Card>
      </Box>
    </Stack>
  );
}
```

## Related components

* For horizontal layouts, use [Cluster](../Cluster/Cluster.md)
* For grid layouts, use [Tiles](../Tiles/Tiles.md)
* For responsive layouts that switch between horizontal and vertical, use
  [ResponsiveSwitcher](../ResponsiveSwitcher/ResponsiveSwitcher.md)

## Accessibility

Stack uses semantic HTML and maintains proper spacing for readability. The
component preserves the natural document flow, ensuring good keyboard navigation
and screen reader compatibility.


## Props

### Web

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `align` | `"center" | "end" | "start"` | No | — | The alignment of the stack. |
| `ariaAttributes` | `AriaAttributes` | No | — | Standard HTML aria attributes. Accepts all standard HTML aria attributes. |
| `as` | `CommonAllowedElements` | No | `div` | The HTML tag to render the container as. Defaults to `div`. |
| `autoWidth` | `boolean` | No | `false` | Whether to allow the stack to take the width of the content. Defaults to 100% |
| `dataAttributes` | `{ [key: `data-${string}`]: string; }` | No | — | Standard HTML data attributes. Accepts anything in a {{"data-key":"value"}} format. |
| `gap` | `GapSpacing` | No | `spaceTokens.base` | The amount of space between the children. Semantic tokens are available. |
| `id` | `string` | No | — | Standard HTML id attribute. |
| `recursive` | `boolean` | No | — | Whether to recursively apply the stack spacing to all the children, not just the top-level. |
| `role` | `AriaRole` | No | — | Standard HTML role attribute. |
| `splitAfter` | `1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15` | No | — | Setting this will push the stack down to the bottom of the parent container, after the number of children provided (1... |
| `UNSAFE_className` | `{ container?: string; }` | No | — | **Use at your own risk:** Custom class names for specific elements. This should only be used as a **last resort**. Us... |
| `UNSAFE_style` | `{ container?: CSSProperties; }` | No | — | **Use at your own risk:** Custom style for specific elements. This should only be used as a **last resort**. Using th... |