English
Sections and Columns
The SectionBlock is the layout primitive in Templatical. Every multi-column layout is built by creating a section and placing blocks inside its columns.
Column layouts
Email best practice
Stick to 1-2 columns for most emails. Three-column layouts become cramped on mobile when columns stack vertically, and some email clients handle 3-column layouts inconsistently. Four columns are tighter still.
The columns property accepts one of these layout presets:
| Value | Description | Column widths |
|---|---|---|
'1' | Single column | 100% |
'2' | Two equal columns | 50% / 50% |
'3' | Three equal columns | 33% / 33% / 33% |
'4' | Four equal columns | 25% / 25% / 25% / 25% |
'2-1' | Two-thirds / one-third | 66% / 33% |
'1-2' | One-third / two-thirds | 33% / 66% |
'3-1' | Three-quarters / one-quarter | 75% / 25% |
'1-3' | One-quarter / three-quarters | 25% / 75% |
'1-2-1' | One-quarter / half / one-quarter | 25% / 50% / 25% |
ts
type ColumnLayout = '1' | '2' | '3' | '4' | '2-1' | '1-2' | '3-1' | '1-3' | '1-2-1';Custom column widths
columnWidths overrides the preset's split. It is one number per column of columns. The shares are scaled to 100 in hundredths. Each column is floored, then raised to at least 0.01, and each leftover hundredth goes to the largest fractional remainder. A tie goes to the earlier column. [1, 1, 2] is 25% / 25% / 50%. [1, 1, 1] is 33.34% / 33.33% / 33.33%. [6, 2, 2, 2] is 50% / 16.67% / 16.67% / 16.66%. The row totals 100. columns still sets the column count. Preset rows stay the literals in COLUMN_LAYOUT_PERCENTS.
ts
import { createSectionBlock } from '@templatical/types';
const row = createSectionBlock({
columns: '3',
columnWidths: [1, 1, 2],
children: [[], [], []],
});Absent columnWidths keeps the preset. The renderer writes each share on mj-column as width, for example width="25%", width="25%" and width="50%". stackOnMobile: false wraps those columns in <mj-group>, the same as a preset.
columnWidths is ignored when its length differs from the layout's column count, or when a value is not a finite number above 0. The preset's split renders, and structure.column-widths-ignored names the reason, count or value.
In the editor, a section with two or more columns shows a Column widths row under Columns. Each field is that column's share. Editing a column gives the difference to the column on its right, and editing the last column gives it to the column on its left. An edit leaves each of the two columns at least 5%, or half of their combined share when the pair is narrower than 10% (an imported [1, 1, 98] keeps 1% / 1%). Columns shows Custom while any usable override is stored, including 50% / 50% on a two-column section. Choosing a preset clears the custom widths.
COLUMN_LAYOUT_PERCENTS is the preset table the renderer emits: "1" is [100], "2" is [50, 50], "3" is [33.33, 33.33, 33.34], "4" is [25, 25, 25, 25], "1-2" is [33.33, 66.67], "2-1" is [66.67, 33.33], "1-3" is [25, 75], "3-1" is [75, 25], "1-2-1" is [25, 50, 25]. sectionColumnPercents returns that row, or the scaled override. columnWidthsIssue returns "count", "value" or null.
Creating sections
Use createSectionBlock from @templatical/types:
ts
import {
createSectionBlock,
createTitleBlock,
createParagraphBlock,
createImageBlock,
} from '@templatical/types';
// Empty two-column section
const section = createSectionBlock({ columns: '2' });
// Section with pre-populated columns
const hero = createSectionBlock({
columns: '1-2',
children: [
[createImageBlock({ src: 'https://cdn.example.com/logo.png', width: 120 })],
[
createTitleBlock({ content: '<h1>Welcome</h1>', level: 1 }),
createParagraphBlock({ content: '<p>Get started in minutes.</p>' }),
],
],
});The children array
children is a Block[][] -- an array of arrays. Each inner array represents the blocks inside one column, ordered left to right.
ts
// For a '2' layout:
section.children = [
[blockA, blockB], // Left column
[blockC], // Right column
];
// For a '3' layout:
section.children = [
[blockA], // Left
[blockB], // Center
[blockC], // Right
];The length of children must match the number of columns in the chosen layout. When you change columns, the editor automatically adjusts children -- merging excess columns into the last column or adding empty arrays for new columns.
Adding blocks to columns
To programmatically add a block to a specific column:
ts
// Add a button to the second column (index 1)
section.children[1].push(
createButtonBlock({
text: 'Learn More',
url: 'https://example.com/docs',
}),
);Nesting
Sections cannot be nested inside other sections. Each section sits at the top level of the template's block list. Within a column, you can place any non-section block type: titles, paragraphs, images, buttons, tables, custom blocks, and so on.
Responsive behavior
On desktop, columns render side-by-side at their defined widths. On smaller screens, columns stack vertically in source order (left column on top) — MJML's default.
stackOnMobile opts out. Omit it or set true to keep stacking. false wraps the columns in <mj-group> so they stay side by side on mobile. The section toolbar exposes the toggle on multi-column sections. A one-column section never emits mj-group.
ts
const row = createSectionBlock({ columns: '2', stackOnMobile: false });You can use the visibility property on individual blocks within columns to show or hide content per breakpoint:
ts
const block = createParagraphBlock({
content: '<p>Desktop only sidebar content</p>',
});
block.visibility = {
desktop: true,
mobile: false,
};See Styling for more on block visibility.
Section-level styles
Sections support the same BlockStyles as other blocks. Common use cases include setting a background color or padding on the entire row:
ts
const section = createSectionBlock({ columns: '1' });
section.styles = {
backgroundColor: '#f8fafc',
padding: { top: 32, right: 24, bottom: 32, left: 24 },
};Sections also accept a borderRadius (in px, a section-specific property) for rounded corners — useful for a card-style section on a contrasting background:
ts
const card = createSectionBlock({ columns: '1', borderRadius: 12 });
card.styles.backgroundColor = '#ffffff';Background image
A section's backgroundImage paints an image behind its columns. Set styles.backgroundColor as well, as the fallback while the image loads and in clients that don't show background images. In the editor's Background panel you also choose the size (Fill, Fit or Original), a nine-point position and whether the image repeats. See the Section block for the email client notes on background images.
Hero
A one-column section with a background image can render as a hero — an mj-hero, where the image fills the box and the content sits on top of it. Set hero:
ts
const banner = createSectionBlock({
columns: '1',
backgroundImage: {
...createBackgroundImage('https://cdn.example.com/hero.jpg'),
naturalWidth: 1200,
naturalHeight: 800,
},
hero: { height: 'image', verticalAlign: 'middle' },
});
banner.styles.backgroundColor = '#1f2937';height: 'image' makes the box as tall as the image drawn across its desktop width, which needs the image file's size in backgroundImage.naturalWidth / naturalHeight. A phone keeps that height and crops the image at the sides to cover the narrower box. A media pick that knows the size (width / height on the asset or the onRequestMedia result) stores it with the URL; otherwise the editor measures the image. A number is a fixed height in px, padding included. In the editor, the Background panel's Height switches between Fit content (no hero), Match image and Fixed, and Content position places the content. The palette's Hero shortcut inserts one to fill in: a hero-mode section with a title, a paragraph and a button on a dark fill. See the Section block for the email client notes.
Outer frame (wrapper)
To frame a section in a colored band — e.g. a white card sitting on a blue background — set wrapper. It renders an mj-wrapper around the section, with its own background, padding, and corner radius. The band is as wide as the email body (settings.width), unless fullWidth is set. fullWidth: true is MJML's full-width="full-width": the band's background color and background image span the recipient's window, and the section stays at settings.width. A corner radius is ignored while fullWidth is on — a window-wide band has no visible corners — and the stored radius is used again when fullWidth is off:
ts
const card = createSectionBlock({ columns: '1', borderRadius: 12 });
card.styles.backgroundColor = '#ffffff';
card.wrapper = {
backgroundColor: '#1e3a8a',
padding: { top: 24, right: 24, bottom: 24, left: 24 },
borderRadius: 16,
};The wrapper's padding is what makes the band show around the section. In the editor, enable it from the Wrapper panel in the section toolbar. Full-width background in the section's Background panel sets fullWidth. With no wrapper yet, turning it on moves the section's own background color and image onto a new wrapper and clears them on the section, so the content sits transparent over the band. While the switch is on, that panel's color and image edit the band (wrapper.backgroundColor and wrapper.backgroundImage), and Content background under them sets the section fill (styles.backgroundColor; empty leaves the content transparent over the band). The Wrapper panel shows the same band color and image. While the switch is off, color and image edit the section fill and Content background is hidden. Turning the switch off clears fullWidth. A wrapper that holds only that band is removed and its current color and image return to the section. If the section already has a content fill, the wrapper stays with fullWidth cleared so neither color is discarded. The wrapper is a styling layer, not a container — sections still cannot be nested. An embedder-owned card around the authored sections is a layout overlay.