# email-image

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## 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

```ts
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:

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