Configuration Guide

All PDF generation methods accept a PDFConfig object. Config is deep-merged from multiple levels — see Configuration Priority.

Type Reference

interface PDFConfig {
  pageSize?: "A4" | "A3" | "LETTER" | "LEGAL" | { width: number; height: number };
  margins?: {
    top?: number;
    right?: number;
    bottom?: number;
    left?: number;
  };
  filename?: string;
  scale?: number;
  metadata?: {
    title?: string;
    author?: string;
    subject?: string;
    keywords?: string[];
    creator?: string;
  };
  styles?: {
    backgroundColor?: string;
    defaultFontSize?: number;
    defaultFontFamily?: string;
    defaultTextColor?: string;
    customCSS?: string;
  };
  container?: {
    className?: string;
    style?: React.CSSProperties;
  };
  header?: {
    text: string | string[];
    fontSize?: number;
    fontColor?: string;
    marginTop?: number;
    marginLeft?: number;
    marginRight?: number;
    align?: "left" | "center" | "right";
  };
  footer?: {
    text: string | string[];
    fontSize?: number;
    fontColor?: string;
    marginBottom?: number;
    marginLeft?: number;
    marginRight?: number;
    align?: "left" | "center" | "right";
  };
  watermark?: {
    text: string;
    fontSize?: number;
    color?: string;
    opacity?: number;
    angle?: number;
  };
}

Page Configuration

Option	Type	Default	Description
pageSize	"A4" | "A3" | "LETTER" | "LEGAL" | { width: number, height: number }	"A4"	Page size. Custom sizes in mm.
margins	{ top?, right?, bottom?, left? } (numbers in mm)	20 each	Page margins
filename	string	"document.pdf"	Downloaded file name
scale	number	2	Canvas scale — higher = sharper, larger file

const config = {
  pageSize: "A4",
  margins: { top: 20, right: 20, bottom: 20, left: 20 },
  filename: "report.pdf",
  scale: 2,
};

Styles

Applied to the rendered content before capture. All fields are optional with no defaults (except backgroundColor which defaults to "#ffffff").

Option	Type	Default	Description
styles.backgroundColor	string	"#ffffff"	Background color of the PDF
styles.defaultFontSize	number	—	Font size in px applied to root element
styles.defaultFontFamily	string	—	Font family applied to root element
styles.defaultTextColor	string	—	Text color applied to root element
styles.customCSS	string	—	Injected as a <style> tag into the captured content

const config = {
  styles: {
    backgroundColor: "#ffffff",
    defaultFontSize: 14,
    defaultFontFamily: "Georgia, serif",
    defaultTextColor: "#222222",
    customCSS: `
      .highlight { background: #fff3cd; padding: 4px 8px; border-radius: 4px; }
    `,
  },
};

Container

Controls the wrapper element around your content. Useful for fixing a width so the PDF layout is consistent regardless of the browser window.

Option	Type	Description
container.style	React.CSSProperties	Inline styles on the wrapper div
container.className	string	CSS class added to the wrapper div

const config = {
  container: {
    style: {
      width: "800px",
      margin: "0 auto",
    },
  },
};

Header

Drawn as text above content on every page. Only rendered when header.text is set.

Option	Type	Default	Description
header.text	string | string[]	—	Header text. Supports {pageNumber} and {totalPages}. Pass an array for multi-line.
header.fontSize	number	12	Font size in pt
header.fontColor	string	"#000000"	Hex color string
header.marginTop	number	page margins.top	Distance from top of page in mm
header.marginLeft	number	page margins.left	Left offset for left/right align
header.marginRight	number	page margins.right	Right offset for right align
header.align	"left" | "center" | "right"	"center"	Text alignment

const config = {
  header: {
    text: "Acme Corp — Quarterly Report",
    fontSize: 10,
    fontColor: "#666666",
    marginTop: 10,
    align: "center",
  },
};

Footer

Same as header but positioned at the bottom. Only rendered when footer.text is set.

Option	Type	Default	Description
footer.text	string | string[]	—	Footer text. Supports {pageNumber} and {totalPages}.
footer.fontSize	number	12	Font size in pt
footer.fontColor	string	"#000000"	Hex color string
footer.marginBottom	number	page margins.bottom	Distance from bottom of page in mm
footer.marginLeft	number	page margins.left	Left offset for left/right align
footer.marginRight	number	page margins.right	Right offset for right align
footer.align	"left" | "center" | "right"	"center"	Text alignment

const config = {
  footer: {
    text: "Page {pageNumber} of {totalPages}",
    fontSize: 10,
    marginBottom: 10,
    align: "center",
  },
};

Page Variables

Use {pageNumber} and {totalPages} anywhere in header.text or footer.text:

footer: { text: "Page {pageNumber} of {totalPages} — Confidential" }
// → "Page 1 of 4 — Confidential"

Pass an array for multi-line text:

header: { text: ["Company Name", "Department Report"] }

Watermark

Text stamped diagonally across every page. Only rendered when watermark.text is set.

Option	Type	Default	Description
watermark.text	string	—	Watermark text (required)
watermark.fontSize	number	20	Font size in pt
watermark.color	string	"#888888"	Hex color string
watermark.opacity	number	0.3	Opacity from 0 (invisible) to 1 (solid)
watermark.angle	number	-45	Rotation in degrees

const config = {
  watermark: {
    text: "CONFIDENTIAL",
    fontSize: 60,
    color: "#FF0000",
    opacity: 0.15,
    angle: -45,
  },
};

Metadata

Embedded in the PDF file properties (not visible in the document).

const config = {
  metadata: {
    title: "Q1 Report",
    author: "Finance Team",
    subject: "Quarterly financial summary",
    keywords: ["finance", "Q1", "2024"],
    creator: "EasyPdf",
  },
};

Complete Example

const config: PDFConfig = {
  pageSize: "A4",
  margins: { top: 25, right: 20, bottom: 25, left: 20 },
  filename: "report.pdf",
  scale: 2,
  styles: {
    backgroundColor: "#ffffff",
    defaultFontSize: 13,
    defaultFontFamily: "Arial, sans-serif",
    defaultTextColor: "#333333",
  },
  container: {
    style: { width: "800px", margin: "0 auto" },
  },
  header: {
    text: "ACME Corp — Internal Report",
    fontSize: 10,
    fontColor: "#999999",
    marginTop: 10,
    align: "right",
  },
  footer: {
    text: "Page {pageNumber} of {totalPages}",
    fontSize: 10,
    marginBottom: 10,
    align: "center",
  },
  watermark: {
    text: "CONFIDENTIAL",
    fontSize: 60,
    color: "#FF0000",
    opacity: 0.12,
    angle: -45,
  },
  metadata: {
    title: "Internal Report",
    author: "ACME Corp",
  },
};

Related

• useEasyPdf Hook
• Basic Usage