Flex

The unopinionated flexbox primitive. The CSS-aligned escape hatch under Stack, Row, and Grid — reach for it when you need reverse direction, CSS defaults, or baseline alignment.

Installation

import { Flex } from "@gradeui/ui"

Usage

Flex mirrors the CSS flexbox model directly — direction, gap, align, justify, wrap — and ships with CSS's own defaults. No baked-in rhythm; you pay for exactly the props you set. For the 95% case reach for Stack, Row, or Grid — they're shorter to type and tuned for common layouts. Flex is the escape hatch.

Direction

Flex's defining prop — the only knob Stack and Row don't let you touch. col-reverse and row-reverse are the common reasons to reach for Flex over Row or Stack.

direction="row-reverse"

direction="col"

Top

Middle

Bottom

Align (baseline)

align="baseline" is Flex-only — Stack and Row don't expose it. Useful for icon + heading rows where the caps line should line up.

Wrap

wrap="wrap-reverse" flows overflow lines upward instead of downward — niche but occasionally exactly what a tag cloud wants.

tag 1

tag 2

tag 3

tag 4

tag 5

tag 6

tag 7

tag 8

tag 9

tag 10

Props

Prop	Type	Default	Description
direction	"row" \| "col" \| "row-reverse" \| "col-reverse"	"row"	Main-axis direction. Flex's defining prop — Stack and Row lock this; Flex doesn't.
gap	"none" \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"	"none"	Gap between children. Same scale as Stack, Row, and Grid. Defaults to none — Flex is CSS-default throughout.
align	"start" \| "center" \| "end" \| "stretch" \| "baseline"	"stretch"	Cross-axis alignment. `baseline` is Flex-only — Row and Stack don't expose it.
justify	"start" \| "center" \| "end" \| "between" \| "around" \| "evenly"	"start"	Main-axis distribution.
wrap	"nowrap" \| "wrap" \| "wrap-reverse"	"nowrap"	Wrap behaviour when children overflow. `wrap-reverse` flows extra lines upward.
asChild	boolean	false	Render as the single child element via Radix Slot — stamps Flex's layout classes onto an existing semantic tag.
className	string	—	Extra classes merged onto the root element.

When to use

Reverse direction — row-reverse / col-reverse. Stack and Row can't express either without a className escape.
Baseline alignment — icon + heading rows where caps should line up.
You want CSS defaults rather than Row's items-center gap-md starting point.
Otherwise prefer Stack (vertical), Row (horizontal), or Grid (2D) — they're easier to read and tuned for the common cases.

Sidecar

The Markdown sidecar Studio (and the Grade MCP server, when it ships) reads to understand this component — frontmatter, when- to-use guidance, and canonical examples. Authored once at packages/ui/components/ui/flex.md and shipped inside the published @gradeui/ui tarball.

---
name: Flex
import: "@gradeui/ui"
role: layout
props:
  - direction?: "row" | "col" | "row-reverse" | "col-reverse" (default "row") — main-axis direction
  - gap?: "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" (default "none") — gap between children
  - align?: "start" | "center" | "end" | "stretch" | "baseline" (default "stretch") — cross-axis alignment
  - justify?: "start" | "center" | "end" | "between" | "around" | "evenly" (default "start") — main-axis distribution
  - wrap?: "nowrap" | "wrap" | "wrap-reverse" (default "nowrap") — wrap behaviour when children overflow
  - asChild?: boolean (default false) — render as the child element via Slot
  - className?: string
  - children: React.ReactNode
when_to_use: The unopinionated flexbox primitive — reach for Flex when Stack, Row, or Grid don't quite fit. Specifically when you need reverse direction (`row-reverse` / `col-reverse`), CSS defaults instead of Row's baked-in `items-center gap-md`, or baseline alignment. Otherwise prefer Stack / Row / Grid — they're easier to read and tuned for the 95% case. Flex is the escape hatch, not the default.
composes_with: [any content component]
aliases: [flex, flexbox, flex container, hstack, vstack, horizontal, vertical, generic container, layout view]
---

```jsx
// Reverse direction — last child appears first (e.g. timestamp before avatar).
<Flex direction="row-reverse" gap="sm" align="center">
  <Avatar />
  <span>2m ago</span>
</Flex>
```

```jsx
// CSS-default Flex — no rhythm baked in, opt into each axis deliberately.
<Flex direction="col" justify="between" className="h-full">
  <Header />
  <Footer />
</Flex>
```

```jsx
// Baseline alignment for icon + text where the caps line should line up.
<Flex gap="sm" align="baseline">
  <Icon />
  <h2 className="text-2xl">Heading</h2>
</Flex>
```

Grid

Resizable