/// Layout
Flex
The general-purpose flexbox primitive: full direction/align/justify/wrap vocabulary and a token-scale gap that can vary per breakpoint.
import { Flex } from "@protocore/pds";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.
Relay pipeline
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.
Responsive gap
Vary the gap by viewport with responsiveGap, keyed by breakpoint (xs/sm/md/lg/xl). Each entry applies from its min-width up and cascades until the next larger override.
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.
Usage
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
- 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.
Flex props
| Prop | Type | Default | Description |
|---|---|---|---|
align | enum | — | `align-items` shorthand. |
className | string | — | |
direction | enum | row | `flex-direction`. |
gap | enum | 4 | Gap between children, mapped to `--pds-space-<n>`. |
justify | enum | — | `justify-content` shorthand. |
responsiveGap | Partial<Record<FlexBreakpoint, FlexGap>> | — | 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 | — | |
wrap | enum | nowrap | `flex-wrap`. |