# Column Component — LLM Reference `Column` is a **vertical stacking primitive** that wraps a single cell of content within a `Container` or `Row`. It arranges its children top-to-bottom, handles padding, background styling, borders, alignment, and an optional `maxWidth` constraint that works across modern clients and Outlook Classic. It is the innermost structural layer before leaf components (Text, Image, Button, etc.). --- ## Position in the Document Tree ``` DocumentTree └── Section ← full-width band └── Container ← horizontal column layout, email width └── Column ← vertical child stacking within a cell └── Text / Image / Button / ... ``` A `Column` typically lives as a direct child of a `Container` column slot, or inside a `Row`. It is never used as a root-level node in the `DocumentTree`. --- ## ComponentNode JSON Structure ```json { "id": "unique-string-id", "type": "ColumnComponent", "config": { "padding": "24px", "gap": "12px", "alignItems": "center", "justifyContent": "center", "width": "100%", "height": "200px", "maxWidth": "480px", "backgroundColor": "#ffffff", "borderRadius": "8px", "border": { "width": "1px", "style": "solid", "color": "#e5e7eb" }, "backgroundImage": { "src": "https://example.com/bg.jpg", "repeat": "no-repeat", "size": "cover", "position": "center center" } }, "children": [] } ``` --- ## `ColumnConfig` — Full Property Reference ### Layout & Sizing | Property | Type | Example | Description | |---|---|---|---| | `width` | `string` | `"100%"` | Width of the outer column table. Usually left unset — width is inherited from the parent cell. | | `height` | `string` | `"200px"` | Fixed height applied to the outer table and ``. Padding is inside this height. | | `maxWidth` | `string` | `"480px"` | Caps the rendered content width. Uses a `
` + inner table pattern for Outlook Classic compatibility. See **`maxWidth` behavior** below. | | `gap` | `string` | `"16px"` | Vertical space between children. Only takes effect when there are 2+ children. Rendered as a spacer `` row. | | `padding` | `string` | `"16px 24px"` | Inner padding. Does **not** add to `height` — it is contained within the declared height. | ### Alignment > ⚠️ **Axis mapping is inverted relative to CSS Flexbox.** In this component, `justifyContent` controls the **vertical** axis and `alignItems` controls the **horizontal** axis. This is the opposite of standard CSS flex behavior. | Property | Type | Controls | Options | |---|---|---|---| | `justifyContent` | `"start" \| "center" \| "end"` | **Vertical** alignment (`valign`) | `"start"` → top, `"center"` → middle, `"end"` → bottom | | `alignItems` | `"start" \| "center" \| "end"` | **Horizontal** alignment (`align`) | `"start"` → left, `"center"` → center, `"end"` → right | Both are applied to the inner padding `` and to each child `` in the gap wrapper. ### Visual | Property | Type | Example | Description | |---|---|---|---| | `backgroundColor` | `string` | `"#f9fafb"` | Background fill color applied to the outer `` | | `borderRadius` | `string` | `"8px"` | Rounds all corners. Also applies `overflow: hidden` to clip background. | | `border` | `BorderConfig` | See below | Border applied to the inner border-wrapper table | | `backgroundImage` | `BackgroundImageType` | See below | Background image on the outer `` | --- ## `maxWidth` Behavior `maxWidth` is a special property that constrains the rendered content width in both modern email clients and Outlook Classic (Word rendering engine), which has no support for CSS `max-width`. **How it works:** - The outer column `` stays at `width: 100%` — it always fills its parent cell - Inside it, a `
` tag is rendered (Outlook Classic reads this as `margin: 0 auto`) - Inside `
`, a table with `width={maxWidth}` as an HTML attribute — Outlook Classic respects this as a hard pixel cap - Modern clients receive `max-width: {maxWidth}` as CSS on the same table and behave correctly **When to use:** Use `maxWidth` when a Column sits inside a full-width parent but you want to constrain the readable text width (e.g. a 480px text column inside a 600px Section). ```json "config": { "width": "100%", "maxWidth": "480px" } ``` --- ## `gap` Behavior When `gap` is set and there are **2 or more children**, Column renders a gap wrapper table with alternating content rows and spacer rows: ``` child[0] gap spacer child[1] gap spacer child[2] ``` The spacer `` has `height`, `lineHeight: "1px"`, `fontSize: "1px"` — the email-safe pattern for reliable vertical spacing in all clients. When there is only **1 child**, `gap` has no effect — children are rendered directly without the wrapper table. --- ## `BorderConfig` Specify either a **full border** (all sides) or **individual sides**. Do not mix both. ```json // Full border — all sides "border": { "width": "1px", "style": "solid", "color": "#e5e7eb" } // Per-side — other sides explicitly set to "none" (Outlook-safe) "border": { "bottom": { "width": "2px", "style": "solid", "color": "#6366f1" } } ``` Supported side keys: `"top"`, `"right"`, `"bottom"`, `"left"`. Each side requires all three of: `width`, `style`, `color`. When individual sides are used, all other sides are set to `"none"` explicitly to prevent Outlook Classic from rendering phantom black borders. --- ## `backgroundImage` ```json "backgroundImage": { "src": "https://example.com/texture.jpg", "repeat": "no-repeat", "size": "cover", "position": "center center" } ``` | Property | Options | |---|---| | `repeat` | `"no-repeat"`, `"repeat"`, `"repeat-x"`, `"repeat-y"` | | `size` | `"auto"`, `"cover"`, `"contain"` | | `position` | Any valid CSS `background-position` string | Always pair with `backgroundColor` as an image-load fallback. --- ## React Usage ```tsx import Column, { ColumnConfig } from './Column'; const config: ColumnConfig = { padding: '24px', gap: '16px', alignItems: 'center', justifyContent: 'start', backgroundColor: '#ffffff', };