---
title: Block Types
description: Reference for all 14 built-in block types in Templatical.
---

# 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](/guide/programmatic-templates). For default property values and how to customize them, see [Block & Template Defaults](/guide/defaults).

## Choosing the right block

| Need | Block | Notes |
|------|-------|-------|
| Headings, titles | [Title](#title) | Fixed-size headings (H1-H4) with block-level formatting |
| Body text, paragraphs | [Paragraph](#paragraph) | Rich text with inline formatting via TipTap |
| Photos, banners, logos | [Image](#image) | Optional link wrapping, responsive width |
| Call-to-action | [Button](#button) | Bulletproof buttons that work in all email clients |
| Multi-column layout | [Section](#section) | The only block that holds other blocks |
| Visual separation | [Divider](#divider) | Horizontal line with style options |
| Vertical spacing | [Spacer](#spacer) | Empty space between blocks |
| Social links | [Social Icons](#social-icons) | 17 platforms, 5 icon styles |
| Navigation links | [Menu](#menu) | Horizontal link list with separators |
| Tabular data | [Table](#table) | Data table with optional header styling |
| Video preview | [Video](#video) | Clickable thumbnail (email clients don't support embedded video) |
| Countdown to a deadline | [Countdown](#countdown) | Animated timer; rendering needs Templatical Cloud |
| Raw markup | [HTML](#html) | Escape hatch for custom code |
| Domain-specific content | [Custom](#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](https://tiptap.dev) 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` | `number` | Corner radius in px. Omit or 0 for square corners |
| `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` | `number` | Corner radius in px |
| `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'` | Line width in px, or `'full'` for 100% |

## 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:

```ts
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:

```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.

| 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.

::: tip 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.

::: warning 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](/backend/render#blocks-with-no-renderer). On Cloud the block renders normally — see [Rendering on Cloud](/cloud/rendering).
:::

| 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](/guide/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` | `number` | Corner radius in px (optional; omit or `0` for square corners) |
| `wrapper` | `SectionWrapper` | Optional outer frame — `{ backgroundColor?, padding?, borderRadius? }` — rendered as an `mj-wrapper` band around the section |

## Custom

A user-defined block type powered by field definitions and a Liquid template. See [Custom Blocks](/guide/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 |