The Image Tag

During transformation, dynamic images may be inserted into the sheet by using the "image" tag. This tag must be used in the bodiless form. When processed, the "image" tag loads a file representing the image from the file system and adds the image to the sheet at the tag's location.

In the internal Apache POI library's API, the method "createDrawingPatriarch" is called in order to create the Image. On older Excel spreadsheets (.xls, versions 97-2003), this appears to corrupt other existing drawings such as comments, shapes, and charts. However, on newer Excel spreadsheets (.xlsx, versions 2007+), this leaves existing drawings such as comments, shapes, and charts intact.


  • The "image" tag supports all base tag attributes.
  • pathname: String Required. Load the image from this pathname, either absolute or relative to the current working directory.
  • type: String Optional. Specify the type of the image to be loaded.
    • png The image is a PNG. This is the default.
    • jpeg The image is a JPG.
    • dib The image is a device-independent bitmap (or a .bmp).
    • pict The image is a Mac PICT.
    • wmf The image is a Windows Metafile.
    • emf The image is an enhanced Windows Metafile.
  • rows: int Optional. Specify the number of Excel rows tall the image should be.
  • cols: int Optional. Specify the number of Excel columns wide the image should be.
  • If neither rows nor cols is specified, then the size of the image in the spreadsheet is the natural size of the image.


In this example, two different image types are used. One specifies the rows and columns, and the other one does not.

Here is the template spreadsheet:

Image Template

... gets transformed into...

Image Result