Core Concepts

Images

Use the <Image> component to embed images in your PDF documents. It supports PNG, JPEG, and SVG formats.

Basic Usage

vue

<template>
  <Document>
    <Page size="A4">
      <Image
        src="/logo.png"
        :style="{ width: 150, height: 50, marginBottom: 20 }"
      />
      <Text>Your content here...</Text>
    </Page>
  </Document>
</template>

Image Sources

The src prop accepts various source types:

File path — Relative or absolute path to an image file
URL — Remote image URL (must be CORS-enabled in browser)
Base64 Data URI — Inline base64-encoded image data
Buffer — Node.js Buffer containing image data

<template>
  <Document>
    <Page size="A4">
      <Image
        src="/logo.png"
        :style="{ width: 150, height: 50, marginBottom: 20 }"
      />
      <Text>Your content here...</Text>
    </Page>
  </Document>
</template>

Image Sizing

By default, images render at their natural size. Control dimensions with standard style properties:

Prop	Type	Default	Description
`src`*	`string \| Buffer`	—	Image source. Supports path, URL, data URI, or Buffer.
`style.width`	`number \| string`	—	Image width. If set without height, aspect ratio is preserved.
`style.height`	`number \| string`	—	Image height. If set without width, aspect ratio is preserved.
`style.objectFit`	`'contain' \| 'cover' \| 'fill' \| 'none' \| 'scale-down'`	—	How the image scales to fit its container.
`style.objectPositionX`	`number`	—	Horizontal position of the image within its container.
`style.objectPositionY`	`number`	—	Vertical position of the image within its container.
`style.borderRadius`	`number`	—	Border radius for rounded corners.
`style.opacity`	`number`	—	Opacity from 0 to 1.

Fixed vs Auto Dimensions

vue

<template>
  <Document>
    <Page size="A4">
      <!-- Fixed dimensions -->
      <Image
        src="/photo.jpg"
        :style="{ width: 200, height: 150 }"
      />

      <!-- Auto height (preserves aspect ratio) -->
      <Image
        src="/photo.jpg"
        :style="{ width: 200 }"
      />

      <!-- Auto width (preserves aspect ratio) -->
      <Image
        src="/photo.jpg"
        :style="{ height: 150 }"
      />
    </Page>
  </Document>
</template>

ImageBackground

Use <ImageBackground> to place content over an image:

vue

<template>
  <Document>
    <Page size="A4">
      <ImageBackground
        src="/background.jpg"
        :style="{ width: '100%', height: '100%' }"
      >
        <View :style="{ padding: 40 }">
          <Text :style="{ color: '#fff', fontSize: 24 }">
            Overlay text on image
          </Text>
        </View>
      </ImageBackground>
    </Page>
  </Document>
</template>

SVG Images

SVG files are rendered natively — they scale infinitely without quality loss:

vue

<template>
  <Document>
    <Page size="A4">
      <Image
        src="/icon.svg"
        :style="{ width: 64, height: 64 }"
      />
    </Page>
  </Document>
</template>

For complex SVG graphics, consider using the built-in SVG components which give you direct control over every element.

Image Caching

vue-pdf caches decoded images for performance. On the browser, images are fetched once and reused across document renders. On the server, images are cached in memory for the lifetime of the process.