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

Need	Block	Notes
Headings, titles	Title	Fixed-size headings (H1-H4) with block-level formatting
Body text, paragraphs	Paragraph	Rich text with inline formatting via TipTap
Photos, banners, logos	Image	Optional link wrapping, responsive width
Call-to-action	Button	Bulletproof buttons that work in all email clients
Multi-column layout	Section	The only block that holds other blocks
Visual separation	Divider	Horizontal line with style options
Vertical spacing	Spacer	Empty space between blocks
Social links	Social Icons	17 platforms, 5 icon styles
Navigation links	Menu	Horizontal link list with separators
Tabular data	Table	Data table with optional header styling
Video preview	Video	Clickable thumbnail (email clients don't support embedded video)
Countdown to a deadline	Countdown	Animated timer; rendering needs Templatical Cloud
Raw markup	HTML	Escape hatch for custom code
Domain-specific content	Custom	Your 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.

Property	Type	Description
content	string	HTML content
level	1 | 2 | 3 | 4	Heading level (H1=36px, H2=28px, H3=22px, H4=18px)
color	string	Text color
textAlign	'left' | 'center' | 'right'	Horizontal alignment
fontFamily	string	Font 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.

Property	Type	Description
content	string	HTML content

Image

Displays an image with optional link wrapping.

Property	Type	Description
src	string	Image URL
alt	string	Alt text
width	number | 'full'	Display width in px, or 'full' for 100%
height	number	Display height in px. Omit to derive it from the width and keep the aspect ratio
align	'left' | 'center' | 'right'	Horizontal alignment
borderRadius	BorderRadiusValue	Corner radius in px, or { topLeft, topRight, bottomRight, bottomLeft } per corner. Omit or 0 for square corners
border	BorderValue	{ top, right, bottom, left }, each { width, style, color }, drawn around the image. Width 0 leaves a side undrawn. Omit for no border
decorative	boolean	Hides the image from screen readers and sends an empty alt
linkUrl	string	Wraps image in a link
linkOpenInNewTab	boolean	Link target behavior
placeholderUrl	string	Placeholder shown in the editor when src uses a merge tag

Button

A call-to-action button with customizable appearance.

Property	Type	Description
text	string	Button label
url	string	Link URL
backgroundColor	string	Button background color
textColor	string	Button text color
borderRadius	BorderRadiusValue	Corner radius in px, or one per corner
border	BorderValue	{ 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
fontSize	number	Font size in px
buttonPadding	SpacingValue	Inner padding
fontFamily	string	Font family override
openInNewTab	boolean	Link target behavior
width	number | 'full'	Fixed width in px, or 'full' for 100%. Omit to size to content.
align	'left' | 'center' | 'right'	Placement within the column. No visible effect when width is 'full'.

Divider

A horizontal line separator.

Property	Type	Description
lineStyle	'solid' | 'dashed' | 'dotted'	Line style
color	string	Line color
thickness	number	Line thickness in px
width	number | 'full' | '<n>%'	Line width: pixels, 'full' for the whole column, or a percentage of the column ('50%')

Spacer

Empty vertical space.

Property	Type	Description
height	number	Height in px

HTML

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

Property	Type	Description
content	string	Raw HTML markup

Social Icons

A row of social media icons linking to platform profiles.

Property	Type	Description
icons	SocialIcon[]	List of social icons
iconStyle	'solid' | 'outlined' | 'rounded' | 'square' | 'circle'	Visual style
iconSize	'small' | 'medium' | 'large'	Icon size
spacing	number	Space between icons in px
align	'left' | 'center' | 'right'	Horizontal alignment

17 platforms are supported: Facebook, Twitter/X, Instagram, LinkedIn, YouTube, TikTok, Pinterest, Email, Website, WhatsApp, Telegram, Discord, Snapchat, Reddit, GitHub, Dribbble, and Behance.

Each SocialIcon has:

interface SocialIcon {
  id: string;
  platform: SocialPlatform;
  url: string;
}

Menu

A horizontal navigation menu with text links.

Property	Type	Description
items	MenuItemData[]	Menu items
fontSize	number	Font size in px
fontFamily	string	Font family override
color	string	Text color
linkColor	string (optional)	Link color
textAlign	'left' | 'center' | 'right'	Alignment
separator	string	Character between items
separatorColor	string	Separator color
spacing	number	Space around separator

Each MenuItemData has:

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.

Property	Type	Description
rows	TableRowData[]	Table rows
hasHeaderRow	boolean	Style first row as header
headerBackgroundColor	string (optional)	Header row background
borderColor	string	Border color
borderWidth	number	Border width in px
cellPadding	number	Cell padding in px
fontSize	number	Font size in px
fontFamily	string	Font family override
color	string	Text color
textAlign	'left' | 'center' | 'right'	Cell text alignment

Video

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.

Property	Type	Description
url	string	Video URL (YouTube, Vimeo, etc.)
thumbnailUrl	string	Thumbnail image URL
alt	string	Alt text for thumbnail
width	number | 'full'	Display width in px, or 'full' for 100%
height	number	Display height in px. Omit to derive it from the width and keep the aspect ratio
align	'left' | 'center' | 'right'	Horizontal alignment
openInNewTab	boolean	Link target behavior
placeholderUrl	string	Editor-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.

Property	Type	Description
targetDate	string	ISO date/time the countdown runs to
timezone	string	IANA timezone the target is interpreted in
showDays / showHours / showMinutes / showSeconds	boolean	Which units to display
labelDays / labelHours / labelMinutes / labelSeconds	string	Caption under each unit
separator	':' | '-' | ' '	Character between units
digitFontSize	number	Digit size in px
digitColor	string	Digit colour
labelFontSize	number	Caption size in px
labelColor	string	Caption colour
backgroundColor	string	Block background
fontFamily	string (optional)	Font family override
expiredMessage	string	Shown once the target has passed
expiredImageUrl	string	Image shown instead of the timer once expired
hideOnExpiry	boolean	Hide the block entirely after the target passes

Section

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

Property	Type	Description
columns	ColumnLayout	Column layout preset
children	Block[][]	Array of block arrays, one per column
stackOnMobile	boolean	Omit or true: columns stack on mobile (MJML default). false: stay side by side (mj-group)
borderRadius	BorderRadiusValue	Corner radius in px, or one per corner (optional; omit or 0 for square corners)
border	BorderValue	{ top, right, bottom, left }, each { width, style, color }, drawn around the section box (optional; omit for no border)
wrapper	SectionWrapper	Optional outer frame — { backgroundColor?, padding?, borderRadius? } — rendered as an mj-wrapper band around the section. 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.

Custom

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

Property	Type	Description
customType	string	Unique identifier for the custom block type
fieldValues	Record<string, unknown>	Current values for defined fields
renderedHtml	string	Cached rendered output
dataSourceFetched	boolean	Whether the data source has been fetched