Renderer

@templatical/renderer converts Templatical template JSON to MJML. Works in both browser and Node.js environments.

The renderer produces MJML only. To compile MJML to HTML for email sending, use any MJML library (mjml for Node.js, spatie/mjml-php for PHP, etc.).

npm install @templatical/renderer

renderToMjml(content, options?)

Renders a TemplateContent object to an MJML string.

import { renderToMjml } from '@templatical/renderer';

const mjml = renderToMjml(templateContent);

Parameters:

Parameter	Type	Description
content	TemplateContent	The template to render
options	RenderOptions	Optional rendering configuration

Returns: string -- MJML markup

RenderOptions

interface RenderOptions {
  customFonts?: CustomFont[];
  defaultFallbackFont?: string;
  allowHtmlBlocks?: boolean;      // default: true
}

Option	Default	Description
customFonts	[]	Custom font definitions for <mj-font> declarations in rendered output
defaultFallbackFont	'Arial, sans-serif'	Fallback font stack
allowHtmlBlocks	true	Set to false to strip HTML blocks from output

Utilities

The renderer also exports utility functions:

import {
  escapeHtml,
  escapeAttr,
  convertMergeTagsToValues,
  isHiddenOnAll,
  toPaddingString,
  generateSocialIconDataUri,
  renderBlock,
  getCssClassAttr,
  getCssClasses,
  getWidthPercentages,
  getWidthPixels,
  SOCIAL_ICONS,
  RenderContext,
} from '@templatical/renderer';

escapeHtml(text)

Escapes HTML entities (<, >, &, ", ') in a string. Use when inserting user content into HTML:

escapeHtml('<script>alert("xss")</script>');
// '&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;'

escapeAttr(text)

Escapes a string for safe use in HTML attribute values:

const alt = escapeAttr('Photo of "sunrise" at O\'Hare');
// 'Photo of "sunrise" at O'Hare'

convertMergeTagsToValues(html)

Converts merge tag HTML spans (used internally by the editor's rich text system) back into their plain text syntax. The editor stores merge tags as <span data-merge-tag="..."> elements; this function strips the spans and leaves the raw merge tag syntax:

import { convertMergeTagsToValues } from '@templatical/renderer';

// Input: editor's internal HTML format
const editorHtml = '<span data-merge-tag="{{ first_name }}">First Name</span>';

const cleaned = convertMergeTagsToValues(editorHtml);
// Output: '{{ first_name }}'

TIP

You typically don't need to call this directly -- the renderer calls it internally when processing title and paragraph blocks. It's exported for advanced use cases where you're working with editor HTML outside the normal rendering pipeline.

isHiddenOnAll(block)

Returns true if a block's visibility has all viewports set to false. Useful for skipping blocks that shouldn't render at all:

if (isHiddenOnAll(block)) {
  // Skip this block entirely
}

toPaddingString(padding)

Converts a SpacingValue to a CSS padding string:

toPaddingString({ top: 10, right: 20, bottom: 10, left: 20 });
// '10px 20px 10px 20px'

generateSocialIconDataUri(platform, style, size)

Generates a base64-encoded SVG data URI for a social media platform icon. Used internally by the renderer for social icon blocks:

const uri = generateSocialIconDataUri('twitter', 'circle', 32);
// 'data:image/svg+xml,...'

renderBlock(block, context)

Renders a single block to its MJML representation. Used internally by renderToMjml() but exported for advanced use cases where you need to render individual blocks.

RenderContext

The context object passed to block renderers. Contains render options and font configuration.

getCssClassAttr(block) / getCssClasses(block)

Generate CSS class attributes from a block's visibility settings. Used internally for responsive hiding.

getWidthPercentages(layout) / getWidthPixels(layout, containerWidth)

Calculate column widths for a given ColumnLayout. Returns an array of percentage or pixel values per column.

SOCIAL_ICONS

A map of all built-in social platform SVG icon data, keyed by platform and style.

Compiling MJML to HTML

After rendering to MJML, compile to HTML using any MJML library:

import { renderToMjml } from '@templatical/renderer';
import mjml2html from 'mjml';

const mjml = renderToMjml(templateContent);
const { html } = mjml2html(mjml);

// html is ready to send via your email service

See How Rendering Works for more on the rendering pipeline.