Image

Embed images with sizing, aspect ratio, and cropping.

<Image src="./photo.jpg" width="3in" height="2in" />

Props

Prop	Type	Description
`src`	`string` \| `Uint8Array` \| `ArrayBuffer`	File path, URL, data URI or the image bytes
`width`	`MeasurementValue`	Image width
`height`	`MeasurementValue`	Image height
`alt`	`string`	Alt text
`className`	`string`	Tailwind classes
`compression`	`ImageCompression`	Overrides the inherited compression. Default `"print"`
`float`	`"left"` \| `"right"`	Float at the column edge with text wrapping around

Loading images

Local files

<Image src="./images/logo.png" width="2in" />
<Image src="/absolute/path/to/image.jpg" width="3in" />

Remote URLs

<Image src="https://example.com/photo.jpg" width="4in" />

Bytes and data URIs

<Image src={await storage.download(photo.key)} width="3in" />
<Image src="data:image/png;base64,iVBORw0KGgo..." width="1in" />

Object storage and custom sources

Pass loadFile to render or renderToBuffer to fetch src strings yourself, for example keys in a private bucket. The same function loads the base document and fonts:

await renderToBuffer(<Report photos={photos} />, {
  loadFile: async (key) => {
    const object = await s3.send(new GetObjectCommand({ Bucket, Key: key }));
    return object.Body.transformToByteArray();
  },
});

Each distinct source is loaded once, even if it appears many times.

Supported formats

PNG
JPEG
GIF (static)
BMP

The format is detected from the file contents, not the extension. If an image cannot be loaded or is in another format, render() rejects with an error naming the src. Photos from phones and cameras often store their rotation in EXIF metadata, which Word ignores. React DOCX applies it, so photos appear upright.

Compression

Like Word’s Compress Pictures, images are downsampled to a resolution for the size they are displayed at, then re-encoded. A 12-megapixel photo shown 3 inches wide becomes 660 pixels wide at the default setting, a fraction of the original size. Images are never enlarged.

Setting	Resolution
`"print"` (default)	220 ppi
`"web"`	150 ppi
`"email"`	96 ppi
`"original"`	Embeds the file unchanged
`{ ppi, quality }`	Custom resolution; `quality` (1-100, default 80) applies to JPEG

Set it for a whole document, a part of it, or one image. The closest setting wins:

<Document imageCompression="web">
  <Section>
    <Image src={chart} />                          {/* web */}
    <ImageSettings compression="original">
      <Image src={signature} />                    {/* original */}
      <Image src={photo} compression="print" />    {/* print */}
    </ImageSettings>
  </Section>
</Document>

"original" keeps the bytes as they are, except for photos with an EXIF rotation, which are re-encoded upright at high quality. GIFs are always kept as they are. An image used at several sizes is stored once, at the resolution its largest use needs. Compression uses the sharp package, installed with React DOCX.

Sizing

Units

<Image src="photo.jpg" width="3in" />        // Inches
<Image src="photo.jpg" width="5cm" />        // Centimeters
<Image src="photo.jpg" width="50mm" />       // Millimeters
<Image src="photo.jpg" width="200px" />      // Pixels
<Image src="photo.jpg" width="72pt" />       // Points
<Image src="photo.jpg" width="50%" />        // Percent of the text width
<Image src="photo.jpg" width={2} />          // Number = inches

Width only

Height calculated from original aspect ratio:

<Image src="photo.jpg" width="4in" />

Height only

Width calculated from original aspect ratio:

<Image src="photo.jpg" height="3in" />

Both

Explicit dimensions (may stretch):

<Image src="photo.jpg" width="4in" height="3in" />

No dimensions

Uses the image’s size at 96 pixels per inch, scaled down to fit between the page margins if it is larger, as Word does when inserting a picture:

<Image src="photo.jpg" />

Aspect ratio

Control aspect ratio with Tailwind classes:

// Square
<Image src="photo.jpg" width="2in" className="aspect-square" />

// 16:9 video
<Image src="photo.jpg" width="4in" className="aspect-video" />

// Custom ratio
<Image src="photo.jpg" width="3in" className="aspect-[4/3]" />
<Image src="photo.jpg" width="3in" className="aspect-[2/1]" />

Object fit

Control how image fills the space:

Cover (crop to fill)

<Image
  src="photo.jpg"
  width="2in"
  height="2in"
  className="object-cover"
/>

Crops image to fill dimensions. Maintains aspect ratio, removes overflow.

Contain (fit inside)

<Image
  src="photo.jpg"
  width="2in"
  height="2in"
  className="object-contain"
/>

Scales to fit within dimensions. May have empty space.

Default (stretch)

<Image src="photo.jpg" width="2in" height="2in" />

Stretches to fill. May distort image.

Common patterns

Logo in header

<Section>
  <Section.Header>
    <Paragraph>
      <Image src="./logo.png" width="1in" />
    </Paragraph>
  </Section.Header>
</Section>

Product image

<Paragraph className="text-center">
  <Image
    src="./product.jpg"
    width="4in"
    className="aspect-square object-cover"
    alt="Product photo"
  />
</Paragraph>

Thumbnail grid (in table)

<Table>
  <Tbody>
    <Tr>
      <Td className="p-2">
        <Image src="./img1.jpg" width="1.5in" className="aspect-square object-cover" />
      </Td>
      <Td className="p-2">
        <Image src="./img2.jpg" width="1.5in" className="aspect-square object-cover" />
      </Td>
      <Td className="p-2">
        <Image src="./img3.jpg" width="1.5in" className="aspect-square object-cover" />
      </Td>
    </Tr>
  </Tbody>
</Table>

Screenshot with border

<Paragraph className="text-center mt-4">
  <Image
    src="./screenshot.png"
    width="5in"
    alt="Application screenshot"
  />
</Paragraph>
<Paragraph className="text-center text-sm text-gray-500">
  Figure 1: Application dashboard
</Paragraph>

Floating

By default an image sits in the line like a character. float places it at the left or right edge of the column, with the text wrapping around it:

<Paragraph>
  <Image src={logo} width="1.2in" float="right" />
  The text of this paragraph flows around the logo.
</Paragraph>

Limitations

Floating images align to the left or right edge of the column; free positioning is not supported
No rotation or transforms (other than applying EXIF orientation)
No filters or effects
No SVG support
No animated GIFs (static frame only)

Getting started

Components

Props

Loading images

Local files

Remote URLs

Bytes and data URIs

Object storage and custom sources

Supported formats

Compression

Sizing

Units

Width only

Height only

Both

No dimensions

Aspect ratio

Object fit

Cover (crop to fill)

Contain (fit inside)

Default (stretch)

Common patterns

Logo in header

Product image

Thumbnail grid (in table)

Screenshot with border

Floating

Limitations

​Props

​Loading images

​Local files

​Remote URLs

​Bytes and data URIs

​Object storage and custom sources

​Supported formats

​Compression

​Sizing

​Units

​Width only

​Height only

​Both

​No dimensions

​Aspect ratio

​Object fit

​Cover (crop to fill)

​Contain (fit inside)

​Default (stretch)

​Common patterns

​Logo in header

​Product image

​Thumbnail grid (in table)

​Screenshot with border

​Floating

​Limitations

Props

Loading images

Local files

Remote URLs

Bytes and data URIs

Object storage and custom sources

Supported formats

Compression

Sizing

Units

Width only

Height only

Both

No dimensions

Aspect ratio

Object fit

Cover (crop to fill)

Contain (fit inside)

Default (stretch)

Common patterns

Logo in header

Product image

Thumbnail grid (in table)

Screenshot with border

Floating

Limitations