Image

An image, placed in its row: left, centred or right. Every default it draws comes from image in lib/image.ts; resolveImage validates the props.

Examples

Image

A 320px image placed left, centred and right, each kept left on a phone.

11.4 KB built. Open the built email (opens in a new tab)

const placeholder = 'https://digitalnsw.github.io/images/placeholder/320x180/'

const images: ReadonlyArray<{ align: Align; file: string; alt: string }> = [
  { align: 'left', file: '5.jpg', alt: 'Aerial view of a braided river in blue and white' },
  { align: 'center', file: '9.jpg', alt: 'Sunlight through a tall green forest' },
  { align: 'right', file: '4.jpg', alt: 'Close-up of the veins of a green leaf' },
];

<NswLayout title='Image'>
  {images.map(({ align, file, alt }) => (
    <NswColumns key={align} padding={false} gutter={false} background='white'>
      <NswColumn>
        <NswImg
          src={placeholder + file}
          alt={alt}
          width={320}
          align={align}
          mobileClass='mobile-left'
        />
      </NswColumn>
    </NswColumns>
  ))}
</NswLayout>

Props

Props of NswImg, read from the component
Prop	Type	Default	Description
`mobileClass`	`string`	—	Mobile utility class(es) on the image's wrapper, for a document's own `@media` rule — `mobile-left` keeps a centred or right-aligned image at the left on a phone. (Legacy `mobileClass`.)
`layout`	`Layout`	—	The layout the default width is drawn from: the document's (handed on by `<NswLayout layout>`) unless the image is given one of its own, and the NSW defaults outside a document. Only the default width is drawn from it; an explicit `width` still wins.
`columnWidth`	`number`	—	The content width of the column the image sits in, handed on by `<NswColumns>` so the default width fits the column; an explicit `width` still wins. Set it yourself only for an image in a column of your own.
`devices`	`Devices`	—	Which devices show the image: left out, every device; `desktop` hides it on a phone (`hide-on-mobile`); `mobile` shows it on a phone only — hidden inline everywhere else, shown by the document's `.show-on-mobile` rule, and kept from Windows Outlook by `mso-hide: all` and the `<!--[if !mso]>` comments around it (see `src/lib/devices.ts`), as `<NswSpacer devices>` is.
`src` (required)	`string`	—	Where the image loads from: an `https:` or `http:` address with a full domain, a `cid:` attachment, or a merge tag the sending platform fills in. Required; anything else throws (see `resolveImageSrc`).
`alt` (required)	`string`	—	What the image shows, read out in its place and shown when it does not load. Required: give `''` for an image that is only decoration. A linked image needs real text, since the link is named by it.
`width`	`number`	the content width of the column it sits in (handed on by `<NswColumns>`), or of a full-width column outside one (`layout.width` less the row padding either side)	The width in whole px. Default the content width of the column it sits in (handed on by `<NswColumns>`), or of a full-width column outside one (`layout.width` less the row padding either side).
`height`	`number`	16:9 of the width, as the legacy's; give this or `aspectRatio` for an image of another shape, which Outlook would otherwise stretch	The height in whole px, written as the `height` attribute Windows Outlook draws the image at, ignoring the CSS `height: auto` every other client uses. Default 16:9 of the width, as the legacy's; give this or `aspectRatio` for an image of another shape, which Outlook would otherwise stretch.
`aspectRatio`	`readonly [number, number]`	`[16, 9]`	The image's shape as `[width, height]` (`[4, 3]`, `[1, 1]`), for the height to be worked out from the width. Default `[16, 9]`. Give this or `height`, not both.
`fluid`	`boolean`	`false`	Fill the column's width (`width: 100%`), shrinking on a phone, rather than the fixed `width`. The `width` is still written for Windows Outlook. Default `false`. (Legacy `maxWidth`.)
`align`	`Align`	`center`	Where the image sits in its row: `left`, `center` or `right`. Default `center`.
`background`	`ColorValue`	—	A fill behind the image, painted on its row across the column it sits in: a theme colour name or a hex literal, or `'transparent'` for none; anything else throws (see `resolveColor`). Windows Outlook draws the row only as wide as the image unless it is right-aligned. (Legacy `bgcolor`.)
`href`	`string`	—	Where the image links to: an address `resolveHref` accepts. A linked image needs `alt` text.
`darkSrc`	`string`	—	An image for dark mode, in clients that honour `prefers-color-scheme` in a `<picture>` (Apple Mail); every other client shows `src`.
`motionSrc`	`string`	—	An animated version, shown only to readers who have not asked for reduced motion; everyone else, and every client without `<picture>`, sees `src`.