Default Template Settings

The defaultTemplateSettings configuration presets what a new email template looks like before anyone has touched it, so every template starts on your brand's widths, colors, and typography.

INFO

These settings shape the template the editor starts from, which means they apply to newly created templates only. Loading a saved template or external JSON replaces them with whatever that template carries. Blocks added later inherit these defaults through the template they are added to.

Available Default Settings

Define your settings under the defaultTemplateSettings property within the TOPOL_OPTIONS object:

Email Width

Sets the default width of the email canvas.

defaultTemplateSettings: {
  "emailWidth": 660,
  // other default settings
},

Email Background Color

Sets the background color of the entire email body (outside the content area).

defaultTemplateSettings: {
  "emailBackgroundColor": "#000000",
  // other default settings
},

Block Background Color

Sets the default background color for new content blocks (e.g., text, images).

defaultTemplateSettings: {
  "blockBackgroundColor": "#000000",
  // other default settings
},

Buttons Background Color

Defines the background color used for buttons by default.

defaultTemplateSettings: {
  "buttonsBackgroundColor": "#000000",
  // other default settings
},

Hyperlink Color

Sets the default color for hyperlinks inside content blocks.

defaultTemplateSettings: {
  "hyperlinkColor": "#000000",
  // other default settings
},

Line height

Controls default spacing between lines of text, as a unitless multiplier of the font size.

defaultTemplateSettings: {
  "line-height": 1.3,
  // other default settings
},

INFO

This value is a number, not a CSS length, so write 1.3 rather than "22px".

Headings and Paragraphs

Configurable for h1, h2, h3 and p.

Each of these accepts a full set of CSS-like styling properties, such as:

  defaultTemplateSettings: {
    "h1": {
      "font-family": "Arial, sans-serif",
      "font-size": "24px",
      "font-weight": "700",
      "font-style": "normal",
      "letter-spacing": "1px",
      "text-transform": "uppercase",
      "text-decoration": "underline",
      "background-color": "#000000",
      "color": "#ffffff"
    },
    "p": {
      "font-size": "16px",
      "color": "#333333"
    }
  },

Block-level Defaults

Beyond the heading and paragraph styles above, the default attributes of individual content blocks and structures can be preset. Each key below accepts an object whose properties match the corresponding MJML attributes. Every property is optional, and anything left out keeps the editor's built-in default.

These become the template's own block attributes, which each newly inserted block inherits. Ten block keys are supported: text, button, carousel, divider, gif, image, loop, social, section, and column. Blocks with no key here, such as spacer and HTML, cannot be preset this way.

Text

Defaults for the text block (mj-text).

defaultTemplateSettings: {
  text: {
    "font-family": "Helvetica, Arial, sans-serif",
    "font-size": 14,
    "line-height": 1.5,
    "padding": "15px 15px 15px 15px"
  },
},

Button

Defaults for the button block (mj-button). Supports a nested hover object for hover-state overrides.

defaultTemplateSettings: {
  button: {
    "align": "center",
    "background-color": "#F5A623",
    "color": "#ffffff",
    "border-radius": "3px",
    "border": "1px solid #cccccc",
    "font-family": "Helvetica, Arial, sans-serif",
    "font-size": "13px",
    "font-weight": "bold",
    "font-style": "normal",
    "text-transform": "uppercase",
    "text-decoration": "none",
    "letter-spacing": "1px",
    "line-height": "1.5",
    "padding": "20px 20px 20px 20px",
    "inner-padding": "10px 20px 10px 20px",
    "width": "200px",
    "gradient": "linear-gradient(45deg, #f00, #00f)",
    "container-background-color": "#ffffff",
    "hover": {
      "background-color": "#e85034",
      "color": "#ffffff",
      "border": "1px solid #ffffff",
      "gradient": "linear-gradient(45deg, #00f, #f00)"
    }
  },
},

Carousel

Defaults for the carousel block (mj-carousel).

defaultTemplateSettings: {
  carousel: {
    "icon-width": "44px",
    "tb-width": "110px",
    "tb-border-radius": "6px",
    "tb-hover-border-color": "#fead0d",
    "tb-selected-border-color": "#cacaca",
    "thumbnails": "visible",
    "padding": "10px 15px 10px 15px",
    "border-radius": "0px"
  },
},

thumbnails accepts "visible" or "hidden".

Divider

Defaults for the divider block (mj-divider).

defaultTemplateSettings: {
  divider: {
    "border-color": "#ffffff",
    "border-style": "solid",
    "border-width": "1px",
    "padding": "10px 25px 10px 25px",
    "padding-top": 10,
    "padding-right": 25,
    "padding-bottom": 10,
    "padding-left": 25,
    "container-background-color": "#000000",
    "container-gradient": "linear-gradient(45deg, #f00, #00f)"
  },
},

Gif

Defaults for the gif block (mj-gif).

defaultTemplateSettings: {
  gif: {
    "padding": "25px 25px 25px 25px",
    "align": "center",
    "fluid-on-mobile": "true",
    "border-radius": "8px"
  },
},

align accepts "left", "center" or "right"; fluid-on-mobile is the string "true" or "false".

Image

Defaults for the image block (mj-image). Also applies to the video block, which shares the same MJML tag.

defaultTemplateSettings: {
  image: {
    "padding": "0px 0px 0px 0px",
    "align": "center",
    "fluid-on-mobile": "true",
    "width": "300px",
    "border-radius": "8px"
  },
},

Loop

Defaults for the loop block (mj-loop).

defaultTemplateSettings: {
  loop: {
    "padding": "10px 25px 10px 25px",
    "background-color": "#ffffff",
    "border": "1px solid #cccccc",
    "border-top": "1px solid #cccccc",
    "border-right": "1px solid #cccccc",
    "border-bottom": "1px solid #cccccc",
    "border-left": "1px solid #cccccc",
    "border-radius": "4px",
    "in-group": true,
    "gradient": "linear-gradient(45deg, #f00, #00f)"
  },
},

Social

Defaults for the social block (mj-social).

defaultTemplateSettings: {
  social: {
    "padding": "10px 10px 10px 10px",
    "icon-size": "35px",
    "icon-padding": "5px",
    "align": "center"
  },
},

Section

Defaults for new sections (mj-section).

defaultTemplateSettings: {
  section: {
    "full-width": false,
    "padding": "20px 0px 20px 0px",
    "background-color": "#ffffff",
    "background-url": "https://example.com/bg.jpg",
    "background-size": "cover",
    "background-repeat": "no-repeat",
    "in-group": true,
    "border": "1px solid #cccccc",
    "border-top": "1px solid #cccccc",
    "border-right": "1px solid #cccccc",
    "border-bottom": "1px solid #cccccc",
    "border-left": "1px solid #cccccc",
    "border-radius": "4px",
    "gradient": "linear-gradient(45deg, #f00, #00f)"
  },
},

INFO

Setting section["background-color"] also overrides the global section background, equivalent to setting blockBackgroundColor. When both are given, section["background-color"] is applied last and wins.

Column

Defaults for new columns (mj-column).

defaultTemplateSettings: {
  column: {
    "vertical-align": "top",
    "background-color": "#ffffff",
    "padding": "10px 10px 10px 10px",
    "border": "1px solid #cccccc",
    "border-top": "1px solid #cccccc",
    "border-right": "1px solid #cccccc",
    "border-bottom": "1px solid #cccccc",
    "border-left": "1px solid #cccccc",
    "border-radius": "4px",
    "inner-attributes": true,
    "column-gradient": "linear-gradient(45deg, #f00, #00f)"
  },
},

vertical-align accepts "top", "middle" or "bottom".

Structure Margins

Defines spacing between different structures (rows/sections) in the email.

defaultTemplateSettings: {
  "structure-margin": "15px",
  // other default settings
},

Stack Columns on Mobile

Sets the default value for Stack Columns on Mobile toggle.

defaultTemplateSettings: {
  "stack-columns": true | false,
  // other default settings
},

Template Language Versions

Defines the set of language variants that are automatically created for every new template.

defaultTemplateSettings: {
  langs: [
    { key: "en", primary: true },
    { key: "de" },
    { key: "fr" },
  ],
  // other default settings
},

Mark one language as primary. Leaving the flag out of every entry promotes the first language in the array, and any language without the flag is treated as primary: false, so there is no need to write it out. Marking two languages as primary is not corrected automatically and leaves the template in an inconsistent state, so set it exactly once.

Each key needs at least two characters, and a key repeated in the array is only added once. Supplying langs turns multilingual mode on for new templates even when the multilingual option is not set.

Default Language Preset

This feature works well with Default Language Presets, allowing you to define your own custom languages that are available for users to select from. Learn more in the documentation here.