Skip to content

Block Types ​

Blocks are the building units of every Templatical template. Each block represents a distinct piece of content -- a paragraph, an image, a button. Blocks can be placed directly in the template or inside sections for multi-column layouts. The editor renders them top-to-bottom in the order they appear.

Every block extends a common Block base with shared properties (id, type, styles, displayCondition, visibility), and each type adds its own specific properties.

To create blocks programmatically, see Programmatic Templates. For default property values and how to customize them, see Block & Template Defaults.

Choosing the right block ​

NeedBlockNotes
Headings, titlesTitleFixed-size headings (H1-H4) with block-level formatting
Body text, paragraphsParagraphRich text with inline formatting via TipTap
Photos, banners, logosImageOptional link wrapping, responsive width
Call-to-actionButtonBulletproof buttons rendered through mj-button as HTML tables
Multi-column layoutSectionThe only block that holds other blocks
Visual separationDividerHorizontal line with style options
Vertical spacingSpacerEmpty space between blocks
Social linksSocial IconsPlatform list and six icon styles (solid, outlined, rounded, square, circle, plain)
Navigation linksMenuHorizontal link list with separators
Tabular dataTableData table with optional header styling
Video previewVideoClickable thumbnail (email clients don't support embedded video)
Countdown to a deadlineCountdownAnimated timer; rendering needs Templatical Cloud
Raw markupHTMLEscape hatch for custom code
Domain-specific contentCustomYour own block types with fields and Liquid templates

Title ​

A heading block with fixed size levels. Use titles for headings, section headers, and other prominent text.

Titles are bold (weight 700) on the canvas, while you edit them, and in the email. Inline bold inside a title asks for a heavier weight, which web-safe fonts such as Arial don't have, so it shows only in a font that does.

PropertyTypeDescription
contentstringHTML content
level1 | 2 | 3 | 4Heading level (H1=36px, H2=28px, H3=22px, H4=18px)
colorstringText color
textAlign'left' | 'center' | 'right'Horizontal alignment
fontFamilystringFont family override

Paragraph ​

Body text rendered as HTML. The editor uses Tiptap for inline editing with formatting controls (bold, italic, links, alignment, font size, color, etc.). All formatting is applied inline -- there are no block-level formatting properties.

PropertyTypeDescription
contentstringHTML content

Image ​

Displays an image with optional link wrapping.

PropertyTypeDescription
srcstringImage URL
altstringAlt text
widthnumber | 'full'Display width in px, or 'full' for 100%. See Width on phones
fluidOnMobilebooleanOmit for the automatic rule: full width on a phone only when the image fills its column on desktop. true always emits MJML fluid-on-mobile; false never does. See Width on phones
heightnumberDisplay height in px. Omit to derive it from the width and keep the aspect ratio
align'left' | 'center' | 'right'Horizontal alignment
borderRadiusBorderRadiusValueCorner radius in px, or { topLeft, topRight, bottomRight, bottomLeft } per corner. Omit or 0 for square corners
borderBorderValue{ top, right, bottom, left }, each { width, style, color }, drawn around the image. Width 0 leaves a side undrawn. Omit for no border
decorativebooleanHides the image from screen readers and sends an empty alt
linkUrlstringWraps image in a link
linkOpenInNewTabbooleanLink target behavior
placeholderUrlstringPlaceholder shown in the editor when src uses a merge tag
naturalWidth / naturalHeightnumberThe image file's own size, for the aspect-ratio lock. Never rendered

Button ​

A call-to-action button with customizable appearance.

PropertyTypeDescription
textstringButton label
urlstringLink URL
backgroundColorstringButton background color
textColorstringButton text color
borderRadiusBorderRadiusValueCorner radius in px, or one per corner
borderBorderValue{ top, right, bottom, left }, each { width, style, color }, drawn around the button (optional). For an outline button, set the background to the keyword "transparent" and set textColor too. A new button is #333333 with white text. Clearing the fill exports "transparent", because an omitted fill falls back to MJML's #414141
fontSizenumberFont size in px
lineHeightnumberLabel line height as a multiple of fontSize. Omit for 1.2 (BUTTON_LINE_HEIGHT). It applies to every line of a wrapped label. A value that is not a finite number above 0 is ignored. buttonLineHeight(block) is the value the canvas and the email use.
buttonPaddingSpacingValueInner padding
fontFamilystringFont family override
fontWeight'regular' | 'medium' | 'bold'Label weight: 400, 500 or 700. Omit for bold, which is how a button with no weight renders.
openInNewTabbooleanLink target behavior
widthnumber | 'full' | PercentWidthOmit to fit the label. A number is px. 'full' spans the column. A percentage such as '40%' is a share of the column's content box (the column less the button's side padding). MJML renders it natively, so the button shrinks with its column on a phone.
align'left' | 'center' | 'right'Placement within the column. No visible effect when width is 'full'. A percentage width still uses align.

Divider ​

A horizontal line separator.

PropertyTypeDescription
lineStyle'solid' | 'dashed' | 'dotted'Line style
colorstringLine color
thicknessnumberLine thickness in px
widthnumber | 'full' | '<n>%'Line width: pixels, 'full' for the whole column, or a percentage of the column ('50%')

Spacer ​

Empty vertical space.

PropertyTypeDescription
heightnumberHeight in px

HTML ​

Injects raw HTML into the template. Use this for content that cannot be expressed with other block types.

HTML block content passes through MJML without making it email-safe. Check client support on caniemail and run the compatibility linter for common failures, including inline SVG, forms and unsupported CSS.

The editor and the renderer output this markup unchanged; neither sanitizes it. If the HTML can come from untrusted sources, sanitize content on your server before saving or sending. To leave HTML blocks out of the rendered email entirely, pass allowHtmlBlocks: false to renderToMjml.

PropertyTypeDescription
contentstringRaw HTML markup

Social Icons ​

A row of social media icons linking to platform profiles.

PropertyTypeDescription
iconsSocialIcon[]List of social icons
iconStyle'solid' | 'outlined' | 'rounded' | 'square' | 'circle' | 'plain'Shape. plain is the glyph alone, with no badge or outline
iconTone'brand' | 'dark' | 'light'Optional. Each platform's brand color (the default), or one tone for every icon. A filled shape draws the glyph in white on the tone, or near-black on light
iconSize'small' | 'medium' | 'large'Icon size
spacingnumberSpace between icons in px
align'left' | 'center' | 'right'Horizontal alignment

Email clients that switch to dark mode, such as the Gmail app and Outlook, change the background but leave images as they are. A dark plain or outlined icon therefore carries a faint white halo that is barely visible on light backgrounds and keeps the icon visible as an outline once the background turns dark. Light icons have no halo, so they stay clean on colored bands, but clients that turn a dark background light (the Gmail app on iOS, Outlook for Windows) can hide a light plain or outlined icon. A filled shape avoids both, since its badge brings its own contrast.

These platforms have built-in icons: Facebook, Twitter/X, Instagram, LinkedIn, XING, YouTube, TikTok, Pinterest, Email, Website, WhatsApp, Telegram, Discord, Snapchat, Reddit, GitHub, Dribbble, and Behance.

Each SocialIcon is a built-in icon or a custom icon:

ts
type SocialIcon = BuiltInSocialIcon | CustomSocialIcon;

interface BuiltInSocialIcon {
  id: string;
  platform: BuiltInSocialPlatform; // every SocialPlatform except 'custom'
  url: string;
}

interface CustomSocialIcon {
  id: string;
  platform: 'custom';
  url: string;
  imageUrl: string; // the icon image
  alt?: string;     // read by screen readers in place of the icon
}

Custom icons ​

A custom icon (platform: 'custom') draws your own image in the row, for a network without a built-in icon or for your own artwork:

json
{
  "id": "0193a1b2-7c4d-7e5f-8a9b-0c1d2e3f4a5b",
  "platform": "custom",
  "url": "https://www.artsy.net/partner/example-gallery",
  "imageUrl": "https://cdn.example.com/icons/artsy.png",
  "alt": "Artsy"
}
  • It sits in the same row as the built-in icons, in its place in icons, and links to url.
  • It is drawn as wide as the block's iconSize (24, 32 or 48px), and its height follows the image's proportions, so a square image lines up with the built-in icons.
  • iconStyle and iconTone don't apply to it: the image is shown as it is, with no badge, tint or rounded corners.
  • In the editor, choose Custom icon in an icon's platform list. The image field has the same Browse button and drag-and-drop upload as the image block, through your onRequestMedia handler.
  • The linter reports a custom icon with no image (structure.social-icon-missing-image, an error) and one with no alt text (a11y.social-icon-missing-alt, a warning).
  • In a localized template, alt is translated per language like an image's alt text.

A horizontal navigation menu with text links.

PropertyTypeDescription
itemsMenuItemData[]Menu items
fontSizenumberFont size in px
fontFamilystringFont family override
colorstringText color
linkColorstring (optional)Link color
textAlign'left' | 'center' | 'right'Alignment
separatorstringCharacter between items
separatorColorstringSeparator color
spacingnumberSpace around separator

Each MenuItemData has:

ts
interface MenuItemData {
  id: string;
  text: string;
  url: string;
  openInNewTab: boolean;
  bold: boolean;
  underline: boolean;
  color?: string;
}

Table ​

A data table with optional header row styling.

PropertyTypeDescription
rowsTableRowData[]Table rows
hasHeaderRowbooleanStyle first row as header
headerBackgroundColorstring (optional)Header row background
borderColorstringBorder color
borderWidthnumberBorder width in px
cellPaddingnumberCell padding in px
fontSizenumberFont size in px
fontFamilystringFont family override
colorstringText color
textAlign'left' | 'center' | 'right'Cell text alignment

Video ​

Video blocks use a linked thumbnail rather than an embedded <video>; see caniemail video support.

Displays a video thumbnail that links to the video URL.

Email client note

Email clients do not support embedded video playback. The renderer outputs a clickable thumbnail image that links to the video URL. Always provide a good thumbnailUrl -- it's the only thing recipients see in their inbox.

PropertyTypeDescription
urlstringVideo URL (YouTube, Vimeo, etc.)
thumbnailUrlstringThumbnail image URL
altstringAlt text for thumbnail
widthnumber | 'full'Display width in px, or 'full' for 100%. See Width on phones
heightnumberDisplay height in px. Omit to derive it from the width and keep the aspect ratio
align'left' | 'center' | 'right'Horizontal alignment
openInNewTabbooleanLink target behavior
placeholderUrlstringEditor-only placeholder

Countdown ​

A live countdown to a deadline, rendered as an animated GIF.

Rendering requires Templatical Cloud

An animated GIF has to be generated per recipient at send time, which a browser cannot do. The open-source renderer has no renderer for this block: it emits a templatical:unrenderable-block marker comment and logs a warning, so a send pipeline can detect and refuse it. See Blocks with no renderer. On a hosted backend that can render GIFs, the block renders normally.

PropertyTypeDescription
targetDatestringISO date/time the countdown runs to
timezonestringIANA timezone the target is interpreted in
showDays / showHours / showMinutes / showSecondsbooleanWhich units to display
labelDays / labelHours / labelMinutes / labelSecondsstringCaption under each unit
separator':' | '-' | ' 'Character between units
digitFontSizenumberDigit size in px
digitColorstringDigit colour
labelFontSizenumberCaption size in px
labelColorstringCaption colour
backgroundColorstringBlock background
fontFamilystring (optional)Font family override
expiredMessagestringShown once the target has passed
expiredImageUrlstringImage shown instead of the timer once expired
hideOnExpirybooleanHide the block entirely after the target passes

Section ​

A layout container that holds one or more columns. See Sections and Columns for full details.

PropertyTypeDescription
columnsColumnLayoutColumn layout preset: "1", "2", "3", "4", "1-2", "2-1", "1-3", "3-1", "1-2-1". Widths and column counts are in Sections and Columns.
childrenBlock[][]Array of block arrays, one per column
stackOnMobilebooleanOmit or true: columns stack on mobile (MJML default). false: stay side by side (mj-group)
borderRadiusBorderRadiusValueCorner radius in px, or one per corner (optional; omit or 0 for square corners)
borderBorderValue{ top, right, bottom, left }, each { width, style, color }, drawn around the section box (optional; omit for no border)
backgroundImageBackgroundImageOptional image behind the section — { url, size, position: { x, y }, repeat } — rendered as background-url plus size, position and repeat on the mj-section. size is "cover", "contain" or "auto"; x is "left", "center" or "right"; y is "top", "center" or "bottom". styles.backgroundColor is its fallback. naturalWidth / naturalHeight (optional) are the image file's own size in px; a hero uses them to match its shape.
heroSectionHeroOptional. Renders a one-column section with a background image as an mj-hero, the image filling the box behind the content: { height, verticalAlign }. height is "image" (the box is as tall as the image drawn across its desktop width, from backgroundImage.naturalWidth / naturalHeight) or a fixed height in px, padding included; verticalAlign is "top", "middle" or "bottom". The image always fills the box (size and repeat don't apply) and no border is drawn. With more than one column, no image, or "image" without the size, the section renders as a regular one, and the structure.hero-not-applied warning says why.
wrapperSectionWrapperOptional outer frame — { backgroundColor?, padding?, borderRadius?, backgroundImage?, fullWidth? } — rendered as an mj-wrapper band around the section. fullWidth: true spans the recipient's window (full-width on mj-wrapper) while the section stays at settings.width; a corner radius is ignored while it is on. Absent or false keeps the band at the email width. An embedder-owned card around the authored sections is a layout overlay.

Email client note: borders and corners in Outlook

  • Outlook on Windows ignores border-radius, including the four-value (per-corner) form.
  • Dashed and dotted borders compile, and Outlook's rendering engine often paints them solid.
  • An image border is drawn on the <img>, and Outlook often drops it. Section and button borders sit on the <td>, which is the durable place for a border.

Email client note: background images

  • Set a background color as well. It shows while the image loads, when images are off, and in clients that don't support background images.
  • A merge tag works as the URL (for example {{ hero_url }}). The canvas shows the fallback color for it, since there is no image to load yet. Quotes inside the tag are percent-encoded, so avoid quoted arguments ({{ hero | default: 'x.jpg' }}).
  • Outlook on Windows draws the image with VML, where an image at its original size (auto) tiles from the top center whatever position and repeat say.
  • In Outlook on Windows, a wrapper's background color paints over the section's background image, and an image on both the wrapper and the section breaks the layout. The structure linter warns about both.

Email client note: heroes

  • A hero always renders at a fixed height: classic Outlook on Windows ignores MJML's fluid height and would shrink the box to its content. Match image sets that height to the image's own height across the box, so on a phone the box keeps its desktop height and the image is cropped at the sides to cover it.
  • Outlook on Windows draws the image with VML from the top of the box, at the box's width and the image's own height for that width, clipped to the box. A box shorter than the image shows the image's top, whatever position says.
  • A merge-tag URL works with a fixed height. Match image needs the image's size, which a merge tag can't give until the email is sent. Without the size, Outlook on Windows stretches the image to the box's height.

Custom ​

A user-defined block type powered by field definitions and a Liquid template. See Custom Blocks for full details.

PropertyTypeDescription
customTypestringUnique identifier for the custom block type
fieldValuesRecord<string, unknown>Current values for defined fields
renderedHtmlstringCached rendered output
renderedStylesheetstringThe definition's stylesheet, copied in alongside renderedHtml
dataSourceFetchedbooleanWhether the data source has been fetched