<!-- Protocore Design System — Flex -->
# Flex

- **Category:** Layout (`layout`)
- **Slug:** `layout/flex`
- **Status:** stable
- **Platforms:** web
- **Import:** `import { Flex } from "@protocore/pds";`
- **Docs:** https://pds.protocore.io/components/layout/flex

> The general-purpose flexbox primitive: full direction/align/justify/wrap vocabulary and a token-scale gap that can vary per breakpoint.

## Flex vs Stack

`Flex` is the *general-purpose* flex box: it exposes the whole vocabulary — `row-reverse`, `wrap-reverse`, `baseline` alignment, responsive gaps. `Stack` (and its `HStack`/`VStack` presets) is the *opinionated* single-axis version: a column or row with a gap, and nothing to think about. Prefer `Stack` when the axis is fixed and you want intent to read at a glance; reach for `Flex` when you need the extra axes, reversal, or a gap that changes per breakpoint. Both take `gap` as a step on the `--pds-space-*` scale, never raw pixels. For a two-dimensional card wall, use `Grid` or `SimpleGrid` instead.

## Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `align` | `enum` | no | — | `align-items` shorthand. |
| `className` | `string` | no | — | — |
| `direction` | `enum` | no | `row` | `flex-direction`. |
| `gap` | `enum` | no | `4` | Gap between children, mapped to `--pds-space-<n>`. |
| `justify` | `enum` | no | — | `justify-content` shorthand. |
| `responsiveGap` | `Partial<Record<FlexBreakpoint, FlexGap>>` | no | — | Per-breakpoint gap overrides, e.g. `{ md: 6 }`. Each key applies at `min-width` of the matching `--pds-bp-*` step and cascades up until the next larger override, so you only specify the breakpoints that change. |
| `style` | `CSSProperties` | no | — | — |
| `wrap` | `enum` | no | `nowrap` | `flex-wrap`. |

## Examples

### Basics

`Flex` is a flexbox `<div>` exposing `direction`, `align`, `justify`, `wrap`, and a token-scale `gap`. Here a spread action bar: a title on the start edge, controls pushed to the end.

```tsx
import { Flex, Text, Button } from "@protocore/pds";

export default function FlexBasics() {
  return (
    <Flex align="center" justify="between" gap={4}>
      <Text weight={500}>Relay pipeline</Text>
      <Flex align="center" gap={2}>
        <Button variant="secondary" size="sm">
          Pause
        </Button>
        <Button size="sm">Deploy</Button>
      </Flex>
    </Flex>
  );
}
```

### Wrapping and alignment

Set `wrap="wrap"` to let children reflow onto multiple lines; the `gap` applies on both axes. Combine with `align` and `justify` for full two-dimensional control of a single flex line.

```tsx
import { Flex, Tag } from "@protocore/pds";

export default function FlexWrap() {
  const chains = [
    "Ethereum",
    "Arbitrum",
    "Optimism",
    "Base",
    "Polygon",
    "Avalanche",
    "BNB Chain",
    "Solana",
    "Sui",
    "Aptos",
  ];
  return (
    <Flex wrap="wrap" align="center" gap={2}>
      {chains.map((c) => (
        <Tag key={c} bordered>
          {c}
        </Tag>
      ))}
    </Flex>
  );
}
```

## Do & don't

**Do**

- Use Flex when you need direction reversal, wrap control, or a responsive gap.
- Use Stack/HStack/VStack when the axis is fixed.
- Keep gaps on the token scale (`gap={4}`), including the `responsiveGap` steps.

**Don't**

- Fake a grid with wrapped Flex children — columns won't align across rows (use Grid).
- Pass raw pixel gaps; `gap` is a step on the token scale.
- Reorder with `row-reverse`/`wrap-reverse` in ways that diverge from DOM order.

## Accessibility

**Notes**

- Flex is a presentational flex `<div>` with no role of its own.
- Visual order follows DOM order; avoid `row-reverse`/`wrap-reverse` reordering that desyncs keyboard and reading order from the DOM.

## Related

`stack`, `grid`, `simple-grid`, `center`

---

© Protocore. All rights reserved. Use of the Protocore Design System requires prior written authorization from Protocore (contact@protocore.io). These machine-readable materials must not be ingested into ML-training datasets or derivative design systems. See https://pds.protocore.io/legal/