# Spacer Component — LLM Reference `Spacer` is a **vertical whitespace primitive**. It renders a fixed-height transparent block that creates consistent vertical spacing between components in an email. It has no visual output beyond the space it occupies — no background, no border, no text. It is the correct tool for adding vertical rhythm between layout elements. --- ## Position in the Document Tree ``` DocumentTree └── Section └── Container └── Column └── Heading (Text) └── Spacer ← vertical gap between elements └── Text └── Spacer ← vertical gap before button └── Button ``` `Spacer` is a leaf node. It can be placed anywhere a child component is accepted: inside `Column`, `Row`, directly in a `Container` cell, or between any sibling components. --- ## ComponentNode JSON Structure ```json { "id": "unique-string-id", "type": "SpacerComponent", "config": { "height": "24px", "hideOnMobile": false } } ``` --- ## `SpacerConfig` — Full Property Reference | Property | Type | Required | Default | Description | |---|---|---|---|---| | `height` | `string` | ✓ Yes | — | Height of the vertical space. Must be a px value (e.g. `"16px"`, `"48px"`). | | `hideOnMobile` | `boolean` | No | `false` | When `true`, adds the `hide-on-mobile` CSS class to the outer table. The builder's global stylesheet collapses the spacer on mobile viewports. | --- ## How It Works `Spacer` creates vertical space using three reinforcing techniques for cross-client reliability: 1. **CSS `height`** on the `` — respected by modern email clients 2. **HTML `height` attribute** on both the `` and the `
` — required for Outlook Classic (Word rendering engine), which ignores CSS height on table cells 3. **`fontSize: "0"` and `lineHeight: "0"`** on the `` — suppresses any phantom vertical space that font metrics would otherwise add, even with no visible text content 4. **` `** inside the `` — ensures the cell renders in clients that collapse empty cells The outer table uses `width: 100%` so the spacer spans the full width of its parent column, maintaining layout integrity. --- ## `height` Format `height` must be a **pixel string** (e.g. `"24px"`). The numeric value is parsed and applied as both the CSS `height` and the HTML `height` attribute. Non-px values (e.g. `"1.5rem"`, `"10%"`) will have their integer portion extracted via `parseInt` — the `rem`/`%` unit will be silently dropped and the raw integer used as pixels. Always use `px` units for predictable behavior. ```json // Correct "height": "32px" // Avoid — unit stripped, only "10" used "height": "10%" ``` --- ## `hideOnMobile` When `hideOnMobile: true`, the outer table receives the `hide-on-mobile` CSS class. The builder's global `` stylesheet sets `display: none` on this class for mobile viewports. This allows a large desktop spacer to be hidden on mobile without a second Spacer component. ```json // Large desktop spacer, hidden on mobile { "id": "desktop-spacer", "type": "SpacerComponent", "config": { "height": "48px", "hideOnMobile": true } } // Paired small mobile spacer (always visible) { "id": "mobile-spacer", "type": "SpacerComponent", "config": { "height": "16px" } } ``` --- ## React Usage ```tsx import Spacer, { SpacerConfig } from './Spacer'; const config: SpacerConfig = { height: '24px', }; ``` The component is memoized via `arePropsEqual`. Pass a stable `config` reference to avoid re-renders. --- ## Spacer vs `gap` on Parent Components Both `Spacer` and parent `gap` properties create vertical space, but they serve different purposes: | | `Spacer` | `gap` on `Column` | |---|---|---| | **Mechanism** | Explicit child node in the tree | Config property on the parent | | **Granularity** | Per-gap, any size | Uniform between all children | | **Mobile control** | `hideOnMobile` per spacer | Single value for all gaps | | **Outlook support** | ✓ Full (HTML attribute + CSS) | ✓ Full (spacer `` row) | | **When to use** | Different spacing between specific pairs of children, or mobile-responsive spacing | Uniform spacing between all children in a column | Use `gap` on `Column` when all children should be evenly spaced. Use `Spacer` when you need variable spacing between specific elements, or when you need mobile-specific control over individual gaps. --- ## Common Patterns & Examples ### 1. Standard content gap ```json { "id": "spacer-16", "type": "SpacerComponent", "config": { "height": "16px" } } ``` --- ### 2. Section breathing room (top/bottom of a column) ```json { "id": "spacer-top", "type": "SpacerComponent", "config": { "height": "40px" } } ``` --- ### 3. Large desktop spacer, hidden on mobile ```json { "id": "spacer-hero-gap", "type": "SpacerComponent", "config": { "height": "64px", "hideOnMobile": true } } ``` --- ### 4. Spacer between heading and body text ```json [ { "id": "spacer-ex-heading", "type": "TextComponent", "config": { "text": "

Our latest products

", "fontSize": "24px", "fontWeight": "700" } }, { "id": "spacer-heading-body", "type": "SpacerComponent", "config": { "height": "12px" } }, { "id": "body", "type": "TextComponent", "config": { "text": "

Discover our new arrivals this season.

", "fontSize": "16px" } } ] ``` --- ## Data Bindings `Spacer` supports the `bindings` property on the `ComponentNode`, alongside `id`, `type`, and `config`. Leaf components do not support `dataList` or `itemAlias` — use those on a parent `Container`, `Column`, or `Row` to repeat the component. `visible` and `propertyMap` are fully supported. ```json { "id": "dynamic-spacer", "type": "SpacerComponent", "bindings": { "visible": "layout.showSpacing === true" }, "config": { "height": "32px" } } ``` | Property | Description | |---|---| | `visible` | JS expression evaluated against the Data Layer. Hides this component when falsy. | | `propertyMap` | Maps component property paths (prefixed with `config.`) to Data Layer paths. | > `Spacer` has no meaningful `propertyMap` targets beyond `config.height`. Conditional rendering via `visible` is the primary binding use case. --- ## Rules & Constraints - **`height` is required.** There is no default — omitting it will cause a broken render. Always provide a `px` string value. - **Use `px` units only.** Non-px values are silently truncated to their integer portion and treated as pixels. `"1.5rem"` becomes `1`, `"10%"` becomes `10` — both likely unintended. - **`Spacer` has no visual properties.** It cannot have a background color, border, or content. It is transparent by design. To create a visible divider, use a `Container` or `Row` with a `border` instead. - **Do not use `Spacer` for horizontal spacing.** It always renders at `width: 100%`. Horizontal gaps between siblings are handled by the `gap` property on `Container`, `Column`, or `Row`. - **`hideOnMobile` requires the global stylesheet.** The `hide-on-mobile` class has no effect without the builder's `` CSS. In isolated rendering contexts, the spacer will always be visible regardless of this flag. - **Minimum effective height is `1px`.** `parseInt` falls back to `1` if the height string produces `0` or `NaN`. A `"0px"` spacer renders with `height: 1` in Outlook — use the `Column` or `Row` `gap` property instead if you need truly zero space.