In jsPDF, image alignment is controlled by the image rectangle you pass to addImage(). Supply the image data, format, x, y, width, and height, then calculate x and y for the page edge or content box you want to use. The current TypeScript declaration does not show a named align option such as "center" or "right".
How image placement works in jsPDF
Choose the document unit and page format first. jsPDF uses millimeters by default, supports points, centimeters, inches, pixels, picas, em, and ex, and uses A4 as its default page format according to the constructor documentation. Coordinates and target dimensions use the unit configured in the constructor.
import { jsPDF } from "jspdf";
const doc = new jsPDF({
unit: "mm",
format: "a4",
orientation: "portrait"
});
The method signature is effectively doc.addImage(imageData, format, x, y, width, height, alias?, compression?, rotation?). The official basic example uses explicit coordinates and dimensions, so alignment is geometry rather than a CSS-like property.
Formulas for every common alignment
Define a containing rectangle with left edge left, top edge top, width boxWidth, and height boxHeight. Define the target image rectangle as imageWidth by imageHeight.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →#1 Best Overall
![PDF Extra 2024| Complete PDF Reader and Editor | Create, Edit, Convert, Combine, Comment, Fill & Sign PDFs | Lifetime License | 1 Windows PC | 1 User [PC Online code]](https://m.media-amazon.com/images/I/41eZq4aiipL._SL160_.jpg)
- EDIT text, images & designs in PDF documents. ORGANIZE PDFs. Convert PDFs to Word, Excel & ePub.
- READ and Comment PDFs – Intuitive reading modes & document commenting and mark up.
- CREATE, COMBINE, SCAN and COMPRESS PDFs
- FILL forms & Digitally Sign PDFs. PROTECT and Encrypt PDFs
- LIFETIME License for 1 Windows PC or Laptop. 5GB MobiDrive Cloud Storage Included.
Horizontal alignment
- Left:
x = left - Center:
x = left + (boxWidth - imageWidth) / 2 - Right:
x = left + boxWidth - imageWidth
Vertical alignment
- Top:
y = top - Middle:
y = top + (boxHeight - imageHeight) / 2 - Bottom:
y = top + boxHeight - imageHeight
To center in both directions, use the center equation for both coordinates. If the image is larger than the box, the result is negative on one axis; that is a deliberate overflow, not an automatic crop.
Center an image on the page
Centering on the entire sheet is different from centering inside a margin box. This example centers an 80 mm by 50 mm image inside an A4 page’s usable width, while keeping a 15 mm margin on both sides.
const pageWidth = doc.internal.pageSize.getWidth();
const pageHeight = doc.internal.pageSize.getHeight();
const margin = 15;
const imageWidth = 80;
const imageHeight = 50;
const x = margin + (pageWidth - 2 * margin - imageWidth) / 2;
const y = 40;
doc.addImage(imageData, "PNG", x, y, imageWidth, imageHeight);
doc.save("aligned.pdf");
The page-size methods are exposed by the current declarations, but check the version installed in your project because public APIs can evolve. If your layout has different left and right margins, replace 2 * margin with leftMargin + rightMargin.
Align an image inside a content box
Use a box whenever the image belongs beside a heading, inside a card, or within a table-like layout.
const left = 20;
const top = 60;
const boxWidth = 170;
const boxHeight = 90;
const imageWidth = 100;
const imageHeight = 62.5;
const x = left + (boxWidth - imageWidth) / 2;
const y = top + (boxHeight - imageHeight) / 2;
doc.addImage(imageData, "JPEG", x, y, imageWidth, imageHeight);
For an image aligned to the right of the same box, use const x = left + boxWidth - imageWidth;. For bottom alignment, use const y = top + boxHeight - imageHeight;.
Preserve the image’s aspect ratio
addImage() requires both target dimensions. Supplying unrelated width and height values stretches or squashes the source. If the source is iw by ih pixels and the target width is tw, derive the height:
const th = tw * ih / iw;
Then use tw and th in the alignment equations. A reusable helper keeps the calculation in one place:
function centeredImage(doc, imageData, format, box, source, targetWidth) {
const targetHeight = targetWidth * source.height / source.width;
const x = box.left + (box.width - targetWidth) / 2;
const y = box.top + (box.height - targetHeight) / 2;
doc.addImage(imageData, format, x, y, targetWidth, targetHeight);
}
centeredImage(
doc,
imageData,
"PNG",
{ left: 20, top: 30, width: 170, height: 100 },
{ width: 1600, height: 1000 },
140
);
A GitHub discussion about avoiding distortion illustrates this as a sizing concern, not as a special alignment mode; treat the issue discussion as user context rather than normative API documentation.
Rank #2
- Edit PDFs with Ease. Modify text, images, and layouts directly within your PDF documents.
- Convert & Organize. Export PDFs to Word, Excel, or ePub, and organize files with ease.
- Read & Annotate. Enjoy intuitive reading modes and powerful tools to comment, highlight, and mark up PDFs.
- Create & Manage PDFs. Create new PDFs, combine multiple files, scan documents, and compress for easy sharing.
- Fill & Sign Forms. Complete forms and digitally sign documents with secure e-signature tools.
Contain versus cover
Contain: show the whole image
To fit an image completely inside a box, calculate the smaller scale factor:
const scale = Math.min(boxWidth / iw, boxHeight / ih);
const tw = iw * scale;
const th = ih * scale;
const x = left + (boxWidth - tw) / 2;
const y = top + (boxHeight - th) / 2;
doc.addImage(imageData, "PNG", x, y, tw, th);
This may leave empty space on two sides. There is no documented automatic contain mode in addImage(); you perform the calculation yourself.
Cover: fill the box and crop
Use Math.max(boxWidth / iw, boxHeight / ih) to make the image cover the box, then crop the excess deliberately. Cropping normally requires a pre-cropped source or a clipping approach in your PDF drawing code. Merely passing the larger dimensions will overflow the box; it does not automatically crop.
Complete browser example
This example loads a data URL, preserves its proportions, centers it in a margin box, and saves the PDF. In a browser, the image must be available as a data URL, Blob converted to a data URL, or another format accepted by your jsPDF version.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →import { jsPDF } from "jspdf";
const imageData = "data:image/png;base64,...";
const doc = new jsPDF({ unit: "mm", format: "a4" });
const pageWidth = doc.internal.pageSize.getWidth();
const pageHeight = doc.internal.pageSize.getHeight();
const leftMargin = 15;
const rightMargin = 15;
const top = 35;
const boxWidth = pageWidth - leftMargin - rightMargin;
const boxHeight = 120;
const sourceWidth = 1600;
const sourceHeight = 900;
const scale = Math.min(boxWidth / sourceWidth, boxHeight / sourceHeight);
const width = sourceWidth * scale;
const height = sourceHeight * scale;
const x = leftMargin + (boxWidth - width) / 2;
const y = top + (boxHeight - height) / 2;
doc.addImage(imageData, "PNG", x, y, width, height);
doc.save("centered-image.pdf");
Units, margins, transparency, and rotation
Keep one unit throughout
If the document uses millimeters, convert source measurements before calculating. Pixel dimensions describe the bitmap; they are not automatically millimeters. Do not subtract a pixel width from a millimeter page width.
Center the rectangle, not always the artwork
Transparent padding is part of a PNG’s rectangular dimensions. jsPDF centers that rectangle, so visible artwork can appear shifted even when the coordinates are correct. Trim transparent borders in the asset or account for the internal padding when choosing dimensions.
Account for rotation
The optional rotation argument rotates the image, but the unrotated width and height may no longer describe its visible bounding box. For a rotated logo or photograph, allow room for the rotated rectangle and inspect the rendered PDF rather than assuming the original bounds still fit.
doc.addImage(imageData, "PNG", x, y, width, height, undefined, undefined, 15);
Debugging alignment problems
- It is one or two millimeters off: verify that every margin and dimension uses the constructor’s unit, and check asymmetric left and right margins.
- The image looks stretched: derive one target dimension from the source aspect ratio instead of guessing both.
- It is mathematically centered but visually off: inspect transparent borders inside the source file.
- It is clipped after rotation: calculate space for the rotated bounding box or reduce the target dimensions.
- The image is missing: confirm that the data URL or binary data is valid, the format argument matches the data, and the call occurs before
doc.save(). - Different pages behave differently: obtain the page width and height from the active document rather than hard-coding A4 values when formats or orientations can change.
- Coordinates appear inverted: jsPDF examples position images using a top-left-style page coordinate system; verify the behavior against the version installed in your project and the official example.
Performance and reliability considerations
Large source images increase memory use and PDF size. Resize photographs before embedding when print resolution does not require the original pixels. Reuse the optional alias when adding the same image repeatedly, as shown in the official example, instead of preparing many independent copies. Test with the actual page format, asset, browser, and jsPDF version used by your application.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallRank #3
- EVERY PDF TOOL UNLOCKED - 30+ tools in one app: edit text and images, convert, merge, split, compress, sign, OCR, redact, watermark, batch process, and more. No feature gates, no upsells, nothing held back.
- PAY ONCE, OWN FOREVER — A one-time purchase, not a subscription. Other apps runs $240/year — Scrivar is yours for life, with free updates included.
- UNLIMITED eSIGN, BUILT IN — Send contracts and forms for signature and track every step. Recipients sign in their browser with no account or app needed. Replace DocuSign and save hundreds a year.
- PC, MAC, AND WEB — Install on any Win 10/11 PC or macOS 11+ Mac (Intel or Apple Silicon), or work in your browser at scrivar.com. Same tools, same account, everywhere you work.
- OCR + FULL OFFICE CONVERSION — Turn scanned documents into searchable, selectable text, and convert PDFs to and from Word, Excel, and PowerPoint with formatting kept intact.
Or skip the browser setup
If what you really need is a screenshot of a web page rather than an image embedded in a PDF, ScreenshotNeo can return a clean PNG, JPEG, WebP, or PDF from one request. It accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.
cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython:
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
See the ScreenshotNeo documentation for all 63 options, including full-page lazy-image loading, CSS-selector element capture, device presets, custom viewports, retina scale, PDF page settings, custom CSS and JavaScript, clicks, waits, request blocking, headers, cookies, authentication, timezone, geolocation, transparent backgrounds, resizing, TTL caching, signed links, asynchronous webhooks, bulk capture, usage, and OpenAPI details. The free plan includes 1,000 screenshots each month with no card; paid plans start at $5 for 3,000. Sign up free.
FAQ
Does jsPDF have an image-align option?
The inspected current declaration exposes coordinates and dimensions, not a named image alignment flag. Calculate the rectangle’s position.
Can I center an image relative to another image?
Yes. Treat the other image’s left, top, width, and height as the containing box and apply the same formulas.
Why does a transparent PNG look misaligned?
Transparent pixels still occupy the image rectangle. Trim the file or compensate for its internal padding.
Frequently Asked Questions
Does jsPDF have an image-align option?
The inspected current declaration exposes coordinates and dimensions, not a named image alignment flag. Calculate the rectangle’s position.
Can I center an image relative to another image?
Yes. Treat the other image’s left, top, width, and height as the containing box and apply the same formulas.
Why does a transparent PNG look misaligned?
Transparent pixels still occupy the image rectangle. Trim the file or compensate for its internal padding.
Free tools Windows power users keep installed
One-click scans. No signup required.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
