Fragments
A fragment is a reusable chunk of MJML that can be embedded in any template. Think of it as a component in a UI library: define a button once, use it everywhere; tweak the button in one place, every email picks up the change.
What fragments are for
- Consistency. One CTA-button design across every transactional email.
- Speed. Authoring a new template is mostly composition: drop in the header, the body card, the footer.
- Maintenance. Brand color change? Edit the fragment, not every template.
Two flavors
| Type | Used for |
|---|---|
| Component | Visible blocks: buttons, info rows, banners, footers, hero sections. |
| Style | Shared head content: fonts, default attributes, CSS, dark-mode rules. |
The distinction is editorial — both render the same way — but it lets admin tooling group, search, and label fragments meaningfully.
Parameters
Fragments accept named parameters so the same component can be reused with
different content. A button fragment might declare text and href; a card
header might declare title and subtitle.
Parameters can:
- carry a default value that applies when the caller omits the argument
- accept literal text (
text: 'View order') - accept expressions (
href: Order.TrackingUrl) that are resolved at send time against the template's data model
This lets a single fragment serve both static usages (a fixed call-to-action) and dynamic ones (a button whose link points to data on the current record).
How fragments are embedded
Inside a template's MJML, a fragment is invoked by its key with any arguments the call site wants to override. The fragment's MJML is spliced into the template before compilation, so the result is one self-contained MJML document.
A fragment can call other fragments — composition is transitive. The system detects and rejects recursive cycles.
Constraints
- Fragment keys follow the same rules as template keys (lowercase, hyphens, 2–100 chars, unique).
- A fragment's MJML must be syntactically valid.
- Parameter names must be unique within a fragment.
- Referenced fragments must exist; templates won't save against missing keys.