Grid system

The grid system provides table-based layout components for creating responsive email designs that render reliably across all major clients. It supports both semantic fractions (such as 1/2, 2/3) and fixed/percentage widths, while keeping total content width and spacing consistent.

What it is

The grid is implemented with 2 partials:

• columns.html – multi-column rows with automatic width calculation, gutters, per-column alignment, mobile behaviour, and optional “feature” layouts.
• column.html – a single, full-width content column with optional outlines/borders, rounded corners, and controlled padding.

Both components output email-safe <table> markup.

Examples

When to use

Use the grid system to:

• Build single-, two-, or multi-column layouts
• Mix fractions, percentages, and fixed pixel widths within the same row when needed
• Create feature layouts (e.g. a hero image/text pair with asymmetric outer padding) using left/right “feature” modes
• Maintain a consistent content width and gutter/padding rhythm across templates

On mobile, columns are output with mobile-12 to stack and span the available width.

Multi-column rows

• Accepts a total row width, outer padding, and gutter; computes the space available for columns and distributes it by fixed/percent/fraction rules
• Supports a rich set of fraction tokens (e.g. 1/2, 2/3, 3/12) that are resolved to pixel widths, with rounding that preserves the exact total
• Calculates the total gutter/outer padding differently when a featurecolumn is pinned to the left or right, so visual edges align cleanly
• Derives the number of columns either from columns or from the highest definedcolNWidth prop; falls back to equal fractions if no widths are given
• Outputs <th class="column mobile-12 …" width="…"> cells with per-column alignment, bgcolor, mobile class, and optional column separators
• Can reverse visual order (useful for RTL or image/text swaps) by emittingdir="rtl" on the row while keeping logical source order

Single column

• Computes inner width from the page width minus left/right padding, then renders a centred, single-column row.
• Supports outline and individual borders (top/right/bottom/left) with configurable thickness and colour; can also round corners.
• Exposes text alignment, cell alignment, bgcolor, mobile class, and valign.

Props

columns.html

Row-level props

Per-column props (repeat N starting at 1)

column.html

Code examples

Two-column (fractions)

<x-columns columns="2" col1Width="1/3" col2Width="2/3" gutter="16" padding="48">
  <slot:col1>
    <!-- Left column content -->
  </slot:col1>
  <slot:col2>
    <!-- Right column content -->
  </slot:col2>
</x-columns>

Fractions are mapped and rounded so totals match precisely.

Three-column (fixed + percent + fraction)

<x-columns columns="3" col1Width="200" col2Width="33%" col3Width="1/3" gutter="16" padding="32" borderRight>
  <slot:col1>…</slot:col1>
  <slot:col2>…</slot:col2>
  <slot:col3>…</slot:col3>
</x-columns>

• Mixed width types are supported and resolved in order: fixed, percent, then fractions.
• borderRight adds a divider between columns (not the last).

Feature layout (image/text)

<x-columns columns="2" feature="left" col1Width="320" col2Width="1/2" gutter="16" padding="48">
  <slot:col1><!-- Feature image --></slot:col1>
  <slot:col2><!-- Text content --></slot:col2>
</x-columns>

Feature mode adjusts outer padding so the feature column sits flush at the edge.

Single column with outline

<x-column padding="48" outline outlineThickness="2" outlineColor="#cbedfd" textAlign="center" rounded>
  <!-- Centered content inside a boxed panel -->
</x-column>

Controlled inner padding, optional outline/rounded corners, and text alignment.

Do / Don't

Do

• Use fractions for semantic layouts; switch to fixed orpercentage widths when you need exact sizing
• Keep gutter and outer padding consistent for a clean rhythm
• Use reverse when you need visual order flipped without changing source order

Don't

• Hard-code tables for grids – always use the partials to benefit from consistent calculations and mobile behaviour
• Over-nest rows/columns; keep structures shallow for readability and client robustness
• Mix too many unrelated width schemes in one row unless necessary (readability and quality assurance suffer)