> For AI agents: the complete documentation index is available at https://wallarm.github.io/design-system/llms.txt, the full documentation bundle is available at https://wallarm.github.io/design-system/llms-full.txt.

# Stack

A column or row of children with a gap from the spacing scale — `gap` defaults to 4, which is the practical difference from `Flex`. Reach for `VStack` or `HStack` rather than `Stack` with a `direction`: they read better in a tree, and `HStack` centres its items for you. Children have to be elements — a bare string is dropped rather than rendered.

[Source](https://github.com/wallarm/design-system/tree/main/packages/design-system/src/components/Stack) · [Storybook](https://wallarm.github.io/design-system/storybook/?path=/docs/layout-stack--overview)

```tsx
import { Stack } from '@wallarm-org/design-system/Stack';

export const Basic = () => (
  <Stack gap={4}>
    <Box>A</Box>
    <Box>B</Box>
    <Box>C</Box>
  </Stack>
);
```

## Usage

```tsx
import { Stack } from '@wallarm-org/design-system/Stack';
```

## Examples

### Direction

`VStack` and `HStack` are the same component with the direction fixed — and `HStack` also switches `align` to `center`, since a row of mixed heights almost always wants that.

```tsx
import { Flex } from '@wallarm-org/design-system/Flex';
import { HStack, VStack } from '@wallarm-org/design-system/Stack';

export const Direction = () => (
  <Flex direction='column' gap={8}>
    <Flex direction='column'>
      <VStack gap={4}>
        <Box>1</Box>
        <Box>2</Box>
        <Box>3</Box>
      </VStack>
    </Flex>
    <Flex direction='column'>
      <HStack gap={4}>
        <Box>1</Box>
        <Box>2</Box>
        <Box>3</Box>
      </HStack>
    </Flex>
  </Flex>
);
```

### Alignment

`align` positions the children across the stack, not along it: in a column that is left, centre and right.

```tsx
import { Flex } from '@wallarm-org/design-system/Flex';
import { VStack } from '@wallarm-org/design-system/Stack';

export const Alignment = () => (
  <Flex direction='column' gap={8}>
    <Flex direction='column'>
      <VStack align='start'>
        <Box>A</Box>
        <Box>B</Box>
        <Box>C</Box>
      </VStack>
    </Flex>
    <Flex direction='column'>
      <VStack align='center'>
        <Box>A</Box>
        <Box>B</Box>
        <Box>C</Box>
      </VStack>
    </Flex>
    <Flex direction='column'>
      <VStack align='end'>
        <Box>A</Box>
        <Box>B</Box>
        <Box>C</Box>
      </VStack>
    </Flex>
  </Flex>
);
```

### Spacing

`gap` takes the spacing scale rather than a free number, which is what keeps rhythm consistent between two screens built by two people.

```tsx
import { Flex } from '@wallarm-org/design-system/Flex';
import { VStack } from '@wallarm-org/design-system/Stack';

export const Spacing = () => (
  <Flex direction='column' gap={8}>
    <Flex direction='column'>
      <VStack gap={2}>
        <Box>A</Box>
        <Box>B</Box>
        <Box>C</Box>
      </VStack>
    </Flex>
    <Flex direction='column'>
      <VStack gap={4}>
        <Box>A</Box>
        <Box>B</Box>
        <Box>C</Box>
      </VStack>
    </Flex>
    <Flex direction='column'>
      <VStack gap={8}>
        <Box>A</Box>
        <Box>B</Box>
        <Box>C</Box>
      </VStack>
    </Flex>
  </Flex>
);
```

### Wrap

With `wrap`, a row that runs out of width breaks onto the next line instead of overflowing its container.

```tsx
import { Flex } from '@wallarm-org/design-system/Flex';
import { HStack } from '@wallarm-org/design-system/Stack';

export const Wrap = () => (
  <Flex direction='column'>
    <HStack gap={2} wrap='wrap'>
      {new Array(40).fill(null).map((_, index) => {
        const key = `${index + 1}`;
        return <Box key={key}>{key}</Box>;
      })}
    </HStack>
  </Flex>
);
```

### Flex behavior

The four sizing knobs against a fixed parent: `fullWidth` fills it, `flexGrow` takes the leftover space, and `flexShrink={false}` refuses to be squeezed — which is what makes the last row overflow on purpose.

```tsx
import { Flex } from '@wallarm-org/design-system/Flex';
import { HStack, VStack } from '@wallarm-org/design-system/Stack';

export const FlexBehavior = () => (
  <Flex direction='column' gap={8}>
    <Flex direction='column'>
      <HStack gap={4}>
        <Box>A</Box>
        <Box>B</Box>
        <Box>C</Box>
      </HStack>
    </Flex>
    <Flex direction='column'>
      <HStack gap={4} fullWidth>
        <Box>A</Box>
        <Box>B</Box>
        <Box>C</Box>
      </HStack>
    </Flex>
    <Flex direction='column'>
      <HStack>
        <VStack gap={4} flexGrow>
          <Box>A</Box>
          <Box>B</Box>
        </VStack>
        <VStack gap={4}>
          <Box>C</Box>
        </VStack>
      </HStack>
    </Flex>
    <Flex direction='column'>
      <div className='w-48 overflow-hidden border border-gray-300 rounded'>
        <HStack gap={4} flexShrink={false}>
          <Box>A</Box>
          <Box>B</Box>
          <Box>C</Box>
          <Box>D</Box>
          <Box>E</Box>
        </HStack>
      </div>
    </Flex>
  </Flex>
);
```

## Props

| Prop           | Type                                                                                               | Default   | Description |
| -------------- | -------------------------------------------------------------------------------------------------- | --------- | ----------- |
| defaultChecked | `boolean \| undefined`                                                                             |           |             |
| defaultValue   | `string \| number \| readonly string[] \| undefined`                                               |           |             |
| autoFocus      | `boolean \| undefined`                                                                             |           |             |
| id             | `string \| undefined`                                                                              |           |             |
| tabIndex       | `number \| undefined`                                                                              |           |             |
| title          | `string \| undefined`                                                                              |           |             |
| rel            | `string \| undefined`                                                                              |           |             |
| onChange       | `ChangeEventHandler<T, Element> \| undefined`                                                      |           |             |
| align          | `{ start: string; center: string; end: string; stretch: string; baseline: string; }`               | `stretch` |             |
| inline         | `{ true: string; false: string; }`                                                                 | `false`   |             |
| fullWidth      | `{ true: string; }`                                                                                |           |             |
| wrap           | `{ wrap: string; nowrap: string; reverse: string; }`                                               | `nowrap`  |             |
| direction      | `{ row: string; column: string; 'row-reverse': string; 'column-reverse': string; }`                | `column`  |             |
| justify        | `{ start: string; center: string; end: string; between: string; around: string; evenly: string; }` | `start`   |             |
| gap            | `complex`                                                                                          | `4`       |             |
| flexGrow       | `{ true: string; }`                                                                                |           |             |
| flexShrink     | `{ true: string; false: string; }`                                                                 |           |             |
| data-testid    | `string \| undefined`                                                                              |           |             |
| asChild        | `boolean \| undefined`                                                                             | `false`   |             |

### HStack

| Prop           | Type                                                                                               | Default  | Description |
| -------------- | -------------------------------------------------------------------------------------------------- | -------- | ----------- |
| title          | `string \| undefined`                                                                              |          |             |
| defaultChecked | `boolean \| undefined`                                                                             |          |             |
| defaultValue   | `string \| number \| readonly string[] \| undefined`                                               |          |             |
| autoFocus      | `boolean \| undefined`                                                                             |          |             |
| id             | `string \| undefined`                                                                              |          |             |
| tabIndex       | `number \| undefined`                                                                              |          |             |
| rel            | `string \| undefined`                                                                              |          |             |
| onChange       | `ChangeEventHandler<T, Element> \| undefined`                                                      |          |             |
| asChild        | `boolean \| undefined`                                                                             |          |             |
| data-testid    | `string \| undefined`                                                                              |          |             |
| align          | `{ start: string; center: string; end: string; stretch: string; baseline: string; }`               | `center` |             |
| inline         | `{ true: string; false: string; }`                                                                 |          |             |
| fullWidth      | `{ true: string; }`                                                                                |          |             |
| wrap           | `{ wrap: string; nowrap: string; reverse: string; }`                                               |          |             |
| justify        | `{ start: string; center: string; end: string; between: string; around: string; evenly: string; }` | `start`  |             |
| gap            | `complex`                                                                                          |          |             |
| flexGrow       | `{ true: string; }`                                                                                |          |             |
| flexShrink     | `{ true: string; false: string; }`                                                                 |          |             |

### VStack

| Prop           | Type                                                                                               | Default | Description |
| -------------- | -------------------------------------------------------------------------------------------------- | ------- | ----------- |
| title          | `string \| undefined`                                                                              |         |             |
| defaultChecked | `boolean \| undefined`                                                                             |         |             |
| defaultValue   | `string \| number \| readonly string[] \| undefined`                                               |         |             |
| autoFocus      | `boolean \| undefined`                                                                             |         |             |
| id             | `string \| undefined`                                                                              |         |             |
| tabIndex       | `number \| undefined`                                                                              |         |             |
| rel            | `string \| undefined`                                                                              |         |             |
| onChange       | `ChangeEventHandler<T, Element> \| undefined`                                                      |         |             |
| asChild        | `boolean \| undefined`                                                                             |         |             |
| data-testid    | `string \| undefined`                                                                              |         |             |
| align          | `{ start: string; center: string; end: string; stretch: string; baseline: string; }`               |         |             |
| inline         | `{ true: string; false: string; }`                                                                 |         |             |
| fullWidth      | `{ true: string; }`                                                                                |         |             |
| wrap           | `{ wrap: string; nowrap: string; reverse: string; }`                                               |         |             |
| justify        | `{ start: string; center: string; end: string; between: string; around: string; evenly: string; }` |         |             |
| gap            | `complex`                                                                                          |         |             |
| flexGrow       | `{ true: string; }`                                                                                |         |             |
| flexShrink     | `{ true: string; false: string; }`                                                                 |         |             |