#2984·mjml

docs: document all caveats for creating custom components

Author: pimlieCreated Oct 1, 2025Updated Oct 13, 2025

Is your feature request related to a problem? Please describe.

When creating custom components, there are apparently caveats that I dont see anywhere documented.

F.e. the layout I'm implementing has a fixed padding etc, so I created a custom text component something like this (note the variant attribute for why I did it like this):

javascript
// my-text-component
  render() {
    const align = this.getAttribute("align");
    const variant = this.getAttribute("variant");

    const { fontSize, lineHeight, fontWeight, fontFamily, color } =
      textStyles[variant] || textStyles["body-regular"];

    return this.renderMJML(`
<mj-text
  color="${color}"
  font-size="${fontSize}"
  font-weight="${fontWeight}"
  line-height="${lineHeight}"
  font-family="${fontFamily}"
  align="${align}"
  padding-bottom="8px" // <- never applied
>
  ${this.getContent()}
</mj-text>`);
  }

But the problem is that mj-text does not implement a padding itself, the padding is only ever applied by the parent. But as my-text-component does not have a padding attribute, that means that f.e. mj-column won't be able to figure out the padding as it resolves that before rendering.

Describe the solution you'd like

It took me quite a bit of time and spitting through the mjml codebase to figure this behaviour out. Even just looking at the mj-text code it looked as a bug at first, cause the padding attributes are not used in mj-text.

It would have been great as besides being centrally documented on https://documentation.mjml.io/, there was a code-comment with the caveat that explained how padding is applied to mj-text :)

Describe alternatives you've considered

I could create a PR with this caveats, but it would be great to know if they are more caveats like this.

Additional context

If this is already documented but I overlooked that, then sorry. Fwiw I looked here: https://documentation.mjml.io/#creating-a-component, in the linked guide and in the boiler plate repo...