Appearance

Default Template Settings ​

The defaultTemplateSettings configuration allows you to define global defaults for new email templates created in the Topol Plugin editor. This ensures visual consistency, saves time for your users, and helps align email content with your brand or design system from the start.

INFO

These settings apply only when a new template is created (i.e., not loaded from a saved draft or external JSON).

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.

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

Email Background Color ​

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

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

Block Background Color ​

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

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

Buttons Background Color ​

Defines the background color used for buttons by default.

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

Sets the default color for hyperlinks inside content blocks.

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

Line height ​

Controls default spacing between lines of text.

ts
defaultTemplateSettings: {
  "line-height": "22px",
  // other default settings
},

Headings and Paragraphs ​

Configurable for h1, h2, h3 and p.

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

ts
  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 ​

In addition to the heading/paragraph styles above, you can preset the default attributes for every new content block and structure. Each key listed below accepts an object whose properties match the corresponding MJML attributes; all properties are optional and only the ones you set are applied. The rest fall back to the editor's built-in defaults.

These settings are applied whenever a new block (or section/column) is inserted into the canvas, so they're a convenient way to enforce a consistent look-and-feel without forcing users to manually adjust every block.

Text ​

Defaults for the text block (mj-text).

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

ts
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)"
    }
  },
},

Defaults for the carousel block (mj-carousel).

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

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

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

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

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

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

Section ​

Defaults for new sections (mj-section).

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

Column ​

Defaults for new columns (mj-column).

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

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

Stack Columns on Mobile ​

Sets the default value for Stack Columns on Mobile toggle.

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

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

Exactly one language must be marked as primary. If the primary flag is left out completely, the first language in the array is automatically set as primary. Once a language is set as primary, all other languages will implicitly have primary: false, so you don’t need to specify this flag for them.

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.