--- title: "Premade blocks" description: "Premade blocks let users insert prepared parts of an email, such as headers or footers. Define your own premade blocks upfront." url: https://docs.topol.io/email-editor/guide/premade-blocks.html --- # Premade blocks **Premade blocks are prepared sections, such as headers or footers, that users insert into an email in one click.** Define them with the `premadeBlocks` array in the `TOPOL_OPTIONS` object. The array holds one or more collections, each an object with a `name` for the collection and a `blocks` array containing the individual blocks. A collection `name` is required and shows as the group heading in the sidebar. Each block takes a `definition` (its MJML structure) plus either an `img` or a `name`. The editor shows the image when `img` is set and falls back to the block's `name` otherwise. In this example, the `premadeBlocks` array contains two collections, each with a single premade block. ```ts premadeBlocks: [ { name: "Premade Blocks Collection 1", // First collection of premade blocks blocks: [ // Premade block(s) within this collection { img: "https://placehold.co/600x400?text=Premade+Block", // Image URL, recommended width > 330px name: "Premade Block 1", // Used if no Image URL is provided definition: [ { tagName: "mj-section", attributes: { "full-width": "600px", padding: "10px 10px", "mj-class": "section", }, children: [ { tagName: "mj-column", attributes: { width: "100%", "vertical-align": "top" }, children: [ { tagName: "mj-image", attributes: { src: "https://placehold.co/600x400?text=Image", href: "https://yourwebsite.com", alt: "Logo", padding: "0px 0px 0px 0px", "fluid-on-mobile": "false", containerWidth: 600, }, }, { tagName: "mj-text", attributes: { align: "left", padding: "15px 15px 15px 15px", "line-height": 1.5, containerWidth: 600, }, content: "This is your premade block from the first collection", }, ], }, ], }, ], }, ], }, { name: "Premade Blocks Collection 2", // Second collection of premade blocks blocks: [ // Premade block(s) within this collection { img: "https://placehold.co/600x400?text=Premade+Block", name: "Premade Block 2", definition: [ { tagName: "mj-section", attributes: { "full-width": "600px", padding: "10px 10px", "mj-class": "section", }, children: [ { tagName: "mj-column", attributes: { width: "100%", "vertical-align": "top" }, children: [ { tagName: "mj-image", attributes: { src: "https://placehold.co/600x400?text=Image", href: "https://yourwebsite.com", alt: "Logo", padding: "0px 0px 0px 0px", "fluid-on-mobile": "false", containerWidth: 600, }, }, { tagName: "mj-text", attributes: { align: "left", padding: "15px 15px 15px 15px", "line-height": 1.5, containerWidth: 600, }, content: "This is your premade block from the second collection", }, ], }, ], }, ], }, ], }, ], ``` ## Advanced options The Plugin includes a selection of premade block examples out of the box, grouped as Header, Content, E-commerce and Footer. Custom blocks can either replace those examples or sit alongside them, controlled by the boolean `override` option: - If `true`, the editor removes the default groups and displays only what you list. - If `false`, the editor keeps the default groups. Any default group you do not place yourself is appended after your collections, in the order Header, Content, E-commerce, Footer. To configure this option, update the basic `premadeBlocks` structure to the following advanced structure: ```ts premadeBlocks: { blocks: PremadeBlocks[], // your collections and, optionally, preset markers override: boolean // required when using this structure } ``` > **WARNING** > > `override` is required in the advanced structure. Omitting it fails validation, which leaves the editor with no premade blocks at all and logs a parsing error. Set it explicitly to `false` to keep the defaults. ### Placing the default groups To decide where Topol's default groups appear, reference them inside `blocks` with a preset marker. A marker is an object with a single `preset` key and one of these values: | `preset` | Default group | | --- | --- | | `header` | Header | | `content` | Content | | `ecommerce` | E-commerce | | `footer` | Footer | The sidebar shows collections and markers in the order they appear in the array. This example puts a custom "Dynamic products" collection between Content and E-commerce: ```ts premadeBlocks: { override: false, blocks: [ { preset: "header" }, { preset: "content" }, { name: "Dynamic products", blocks: [ // your premade blocks ], }, { preset: "ecommerce" }, { preset: "footer" }, ], }, ``` A few rules apply: - A marker is a bare reference. A marker with an extra `name` or `blocks` key fails validation. An object carrying all three keys is read as a custom collection, and its `preset` key is ignored. - Each preset can be listed once. Listing one twice fails validation. - Markers work only in the advanced structure. A marker in the basic array fails validation. - With `override: false`, a default group you leave out is still appended at the end. With `override: true`, it is left out. - The group's name and its blocks follow the editor language, so `ecommerce` shows as "Produkty" with the Czech block set when the editor runs in Czech. Like every other validation error on this option, a bad marker leaves the panel empty and logs `Error while parsing premade blocks` to the console with the failing path. ### Transforming the basic structure to the advanced structure Basic structure without the `override` option: ```ts premadeBlocks: [ { name: "Premade Blocks Collection 1", blocks: [ { img: "https://placehold.co/600x400?text=Premade+Block", name: "Premade Block 1", definition: [ { // tagName, attributes, children... }, ], }, ], }, ], ``` Advanced structure with the `override` option: ```ts premadeBlocks: { blocks: [ { name: "Premade Blocks Collection 1", blocks: [ { img: "https://placehold.co/600x400?text=Premade+Block", name: "Premade Block 1", definition: [ { // tagName, attributes, children... }, ], }, ], }, ], override: false, }, ``` To turn the feature off entirely, set `premadeBlocks` to `false`: ```ts premadeBlocks: false, ``` ## Loading specific premade block examples To keep only some of Topol's default **groups**, set `override` to `true` and list the ones you want as preset markers. This keeps only the Footer group next to your own collection: ```ts premadeBlocks: { override: true, blocks: [ { name: "My collection", blocks: [ // your premade blocks ], }, { preset: "footer" }, ], }, ``` There is no built-in way to pick individual **blocks** out of a default group. To use only specific blocks: 1. Use the advanced configuration structure and set the `override` option to `true`. 2. Visit this [GitHub Gist page](https://gist.github.com/tomsq/248aeace303bd11599dd996051350948), which contains the full definitions of all available premade block examples. 3. Identify the blocks you'd like to use, then copy and paste their definitions into your own collection in `premadeBlocks`.