Edit online


This section includes topics that describe how to style graphics in your PDF output.

Edit online


This topic contains information about how you can reference images from your HTML or XML documents.

For HTML, the img tag is recognized as an image without any other styling in your CSS files:

<p> And this is the picture of a happy face: <img src="happy.png" />. </p>

For XML, you must add CSS rules that pick up the content of an attribute and uses it as a source for the image.

<para> And this is the picture of a happy face: <imagedata fileref="happy.png"/>.</para>

The following example uses static content on the imagedata :before pseudo-element:

imagedata[fileref]:before {
    content: attr(fileref, url);

It is important to use the url keyword when retrieving the attribute value. It signals that the value is a pointer to an external image.

Edit online

Image Maps (HTML)

The HTML <map> element is supported by the processor. It allows you to define a set of shapes over your original image and each shape behaves like a link pointing to a part of your publication or to an external resource.

  1. Start by specifying the width and height of your image using attributes. The size and coordinates are in pixels. The size you define here is very important when you specify the coordinates of the shapes. You can use any CSS unit, including percents. The percents are solved relative to the image size and represent a way of creating "responsive" image maps (reusing the map on the same image with different sizes depending on the position in the document). If you are using the same customization CSS for HTML web output as well, make sure you use only pixels as some of the browsers do not support other units.
    <img src="engine-picture.png" width="400" height="300">
  2. Create a map element and link the image to the map:
    <img src="engine-picture.png" width="400" height="300" usemap="mapID">
    <map name="mapID">...</map>
  3. In the map element, add areas, each with a shape and a set of coordinates:
    <area shape="rect" coords="100,70,120,90"
              href="#radiator" alt="Radiator" />
  4. Verify how the shapes look in the output. You can make the shapes visible using one of these methods:
    • Using the -show-image-map-area-shapes and -show-image-map-area-numbers command-line arguments.
    • Adding a CSS snippet to your customization. The shapes have the image-map-shape class, the bullet around the image map number (image-map-number), and the text inside the bullet (image-map-number-text). To make them translucent yellow:
      	fill: yellow;
      	fill-opacity: 0.5;
      	stroke-opacity: 0.5;
      .image-map-number-text {
      	visibility: visible;	
      .image-map-number {
      	fill: yellow;
      	fill-opacity: 0.4;	
      	stroke-opacity: 0.7;
Edit online

Setting Image Width and Height

The image size can be determined from the number of pixels of the image, taking the image resolution into account (if available). There are cases where this computed size is not what you need, and you want to specify the size explicitly.

For HTML, it is enough to use the image attributes directly in your document.

<img src="my_image.png" width="300" height="250" />

For an arbitrary XML, you can indicate the image width and height through a rule that matches the element (or its :before or :after pseudo-elements) and sets the width and height CSS properties.

imagedata {
    display: inline;
    content: attr(src, url);
    width: attr(width, length);
    height: attr(height, length);

Or, if you use an image as a decorator, you can specify fixed dimensions in the CSS:

chapter title:before {
    content: url("my_artwork.png");
    width: 300px;
Note: For static content as in the example above, Oxygen PDF Chemistry tries to use the width and height set on the pseudo-element, then the ones that are set on the parent element, but only if the static content is composed of a single image. Mixing text and images in the content property disables the width and height specification.

If you want to limit the width of the images to a maximum size, you can use the max-width property. The image will be scaled down to fit the maximum size (if it is larger).

imagedata {
    content: attr(src, url);
    max-width: attr(width, length); 
Edit online

Image Resolution

Some raster images (pixels, not vector) may have a default resolution, set by the designer, using an image-editing software. Usually, the image size and resolution are set to look best on the screen. The advantage of a resolution set in the image itself is that it will have the same effective size on the screen and on paper. For example, if the image has 144 dots in width, and an embedded resolution of 72dpi, it will be two inches on screen and on paper.

The problems start to arise when the resolution is not set on the image, and the PDF processor has to decide what resolution to use to determine the size of the graphic. To solve this, the processor extracts the DPI from:

  • The image-resolution CSS property associated to the element that contains the image.
  • The -image-resolution command-line parameter.
  • The built-in fallback resolution of 96 DPI.

The recommended way to change this is by using the CSS Level 4 image-resolution property:

img {
    image-resolution: 300dpi;
Note: The image-resolution is inheritable, so you can associate it to the root element. It does not apply on the page generated content (margin boxes).
:root {
    image-resolution: 300dpi;
To reset the image resolution to the one set in the image itself, you can use the constant from-image instead of a DPI value:
title:before {
    content: url("chapter-decorator.png");
    image-resolution: from-image;
Tip: To change the resolution for images that appear in a page margin box, set this property on that margin box, or directly on the @page rule, to apply it to all page margin boxes:
@page front-page {
    image-resolution: 600dpi;

@page {
    @top-center {
        image-resolution: 600dpi;
        content: url("company-logo.png");
Edit online

Background Images

You can use background images to impose a texture. You can use them to decorate an entire page, or a specific element from your document.

Supported properties:

  • background-image
  • background-repeat
  • background-position

Page Background Images

You can set a background for a page. Usually, you do this for the cover page to impose a full-page artwork, or to add graphics to the header and footer of the page. Here is an example of how can you do it for the page:

@page cover {

div.cover {
    page: cover;
Note: It is better to use SVG for the page artworks. It does not suffer from pixelation. If you are limited to using raster images, you can fine-tune their resolution by using the image-resolution property.
Note: To separate the header and footer from the main content using visual effects (lines, shadows, etc.), you can use a full page size artwork in SVG and set it to the default page:
@page {

If your artwork is smaller, consider a "DRAFT" watermark (for instance). You should use the background-position to place it where you need:

@page {
    background-position: bottom center;

Element Background Images

You can style the background of your elements the same as for web pages:

section {
    background-image: url("my_repeating_pattern.svg");
    background-repeat: repeat-y;
Edit online

Supported Image Types

Oxygen PDF Chemistry supports the following types of raster images:

  • BMP (Microsoft Windows Bitmap)
  • GIF (Graphics Interchange Format)
  • JPEG (Joint Photographic Experts Group)
  • PNG (Portable Network Graphic)
  • TIFF (Tag Image Format File)

And the following types of vector images:

  • SVG (Scalable Vector Graphics)
  • WMF (Windows Metafile)
  • PDF (PDF Documents)

PDF Images

You can reference PDF images the same way other image files are referenced:

<img src="my_doc.pdf"/>

To point to a single page from your PDF document, use the following syntax (this example points to page 5):

<img src="my_doc.pdf#page=5"/>
Edit online


Oxygen PDF Chemistry supports SVG images. The main advantage of using SVG is that the image looks good on paper no matter its size.

SVG Referenced or Embedded in the Document

These can either be referenced as external resources:
<p> This is an SVG showing a happy face: <img src="happy.svg"/></p>
or embedded in the document as SVG fragments:
<p> This is a red circle: 
   <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 50 50" width="50" height="50">
       <circle cx="25" cy="25" r="10" />
The document styles are also applied to the SVG fragments. For instance, if the <circle> element has the sun class, you could change its appearance by using .sun {fill="orange"} in your main CSS. As a general rule of thumb, keep distinct names for the SVG fragment class attributes from the ones used for general content styling.
Note: For HTML5, the namespace declaration is not required.

Using SVG for Styling

To use SVG to decorate an element:

div.note:before {

To set an SVG image as the background of a page, or a page margin box:

@page coverpage{
    background-image: url("images/clipart.svg");
    background-position:center center;
    @top-left {
        background-image: url("images/company.svg");
Note: The image-resolution CSS property does not apply for SVG vectors.

Linking from SVG to Parts of the Host Document

If you need to use the graphics as a type of table of contents, you can place links over parts of the image (used as callouts) that point to some descriptive sections in your document by using the <a xlink:href=".."> markup. This is similar to what the <imagemap> HTML element does, but this is encoded directly in the graphics:

<p> This image has a link that points to a paragraph:
          viewBox="0 0 50 50" 

      <a xlink:href="explain-circle">
        <circle cx="25" cy="25" r="10" />

<p id="explain-circle"> 
  The circle is a round shape.
Edit online


MathML equations can either be referenced from the document as external resources (the file should end with the .mml extension):

<p> The quadratic formula: <img src="quadratic.mml"/></p>

or embedded directly in the document:

  <p> The quadratic formula:
      <mo form="prefix"></mo> <mi>b</mi>
       <msup> <mi>b</mi> <mn>2</mn> </msup>
       <mn>4</mn> <mo></mo> <mi>a</mi> <mo></mo> <mi>c</mi>
      <mn>2</mn> <mo></mo> <mi>a</mi>
  • No styling is required to show the embedded MathML in the output. It works automatically for HTML or XML document types.
  • For HTML5, the namespace declaration is not required.
Edit online

Supported Colors

Along with the usual color values, Oxygen PDF Chemistry supports the following special values for all the color properties:

  • rgb - Used to specify red, green, and blue components (for example, color="rgb(255 , 0 , 153)").
  • rbga - Used for transparent colors by specifying each color channel and the transparency. For example, the following would result in the background color being magenta since the red color from the parent div element will be visible through the blue color of the <p> element:

For more information about color properties, see MDN Web Docs: Color.