Backgrounds and borders

Written for mPDF 8.2 on PHP 8.1+. Updated 2 November 2026.

Backgrounds and borders are where mPDF output starts to look designed rather than printed. Most of the CSS you’d expect works on block elements and table cells.

Colours and borders

.panel {
  background-color: #eef5f4;
  border: 1px solid #0e6b62;
  border-radius: 4mm;
  padding: 5mm;
}
td.total { border-top: 2px solid #222; }

All the border styles are supported (solid, dashed, dotted, double, groove and the rest), with separate sides and per-corner radii. For tables, border-collapse: collapse behaves like a browser, and separate with border-spacing works too.

Background images

.hero {
  background: url('images/texture.jpg') no-repeat center center;
  background-image-resize: 6;
}

background-repeat and background-position work as in CSS. Instead of background-size, mPDF uses its own background-image-resize property:

• 0: natural size
• 1 or 2: fit the width or the height
• 4: resize to fit, keeping proportions
• 5: like 4, but only ever shrinking
• 6: stretch to fill the whole box

Gradients

.banner { background: linear-gradient(to right, #0e6b62, #7cc6bc); }
.badge  { background: radial-gradient(circle, #ffffff, #dde7e6); }

Gradients are drawn as vector shading, so they stay smooth at any zoom.

Full-page backgrounds and letterheads

Put the background on the page itself, so it sits behind the margins as well as the content:

@page {
  background: url('letterhead.png') no-repeat 0 0;
  background-image-resize: 6;
}

This is the usual way to reuse a designed letterhead. Export it as a PNG or JPEG at A4 size (about 2480 × 3508 px at 300 dpi). Named pages let the first page have the full letterhead and later pages a lighter one.

Limits

• Shadows (box-shadow) work on blocks but not on table cells or inline elements.
• Several stacked background images on one element are not supported. Nest elements instead.
• Rounded corners on table cells work best with border-collapse: separate.