email-image

(no submodules)

Purpose

Renders an <img> inside a centring <table> with the canonical responsive-email defaults (display:block, max-width:100%, border:0, outline:none). The alt attribute is required — missing alt text breaks accessibility and triggers spam-filter heuristics in several large providers.

The component is the right choice for hero images, illustrations, and inline graphics. For brand logos that benefit from MSO-specific fall-throughs, callers may render an additional <v:image> block wrapped in a <!--[if mso]> conditional via the renderer's rawHtml helper.

Features

Required alt prop (TypeScript will refuse to compile a missing alt).
Optional pixel width and height set as both HTML attributes and CSS values for Outlook-on-desktop compatibility.
display:block removes the inline-baseline gap that produces a thin border below the image in some clients.
max-width:100% makes images responsive — they scale down inside a narrower container (mobile) but cap at their natural size on desktop.
Wrapper <table> honours the align prop (center by default).

Usage: Basic

import { EmailImage } from "@suaveplan/email-templates/components";
import { renderVNode } from "@suaveplan/email-templates/vnode";

renderVNode(EmailImage({
  src: "https://cdn.example.test/hero.png",
  alt: "A welcoming illustration",
  width: 600,
  height: 300,
}));

Usage: Advanced

A left-aligned logo with rounded corners:

import { EmailImage } from "@suaveplan/email-templates/components";
import { renderVNode } from "@suaveplan/email-templates/vnode";

renderVNode(EmailImage({
  src: "https://cdn.example.test/logo.png",
  alt: "Acme",
  width: 120,
  height: 40,
  align: "left",
  style: { "border-radius": "4px" },
}));

API Reference

Prop	Type	Description
`src`	`string`	Image URL.
`alt`	`string`	Accessible alt text — required.
`width`	`number?`	Pixel width (HTML + CSS).
`height`	`number?`	Pixel height (HTML + CSS).
`theme`	`EmailTheme?`	Theme override (used for the bottom margin).
`align`	`"left" \| "center" \| "right"`	Cell alignment; defaults to `"center"`.
`style`	`StyleObject?`	Additional `<img>` inline styles.

Implementation Notes

The <img> is wrapped in a single-row <table> because Outlook honours the table's align attribute reliably; CSS text-align on a plain <img> would behave inconsistently. The wrapping <td> carries the alignment hint while the <img> itself stays block-level.

width and height set both the HTML attributes and the inline CSS because Outlook-on-Windows preserves the HTML attribute while modern clients use the CSS; the two values must agree.

3.2 KiB Raw Blame History