feat: add webFrameMain.printToPDF() by MarshallOfSound · Pull Request #52439 · electron/electron

MarshallOfSound · 2026-07-24T10:42:25Z

Description of Change

Adds frame.printToPDF(options) to WebFrameMain, allowing the main process to print individual frames (e.g. an <iframe>) to PDF. This reuses the existing webContents.printToPDF implementation, which already operates on a single frame internally — the C++ core and JS option handling are extracted into shared helpers used by both. Print jobs within a frame tree are serialized (the same guarantee webContents.printToPDF already had, as concurrent jobs in one tree conflict in the renderer), while frames in different webContents print concurrently.

resolves #33625
resolves #22796

Checklist

I have built and tested this change
I have filled out the PR description
I have reviewed and verified the changes
npm test passes
tests are changed or added
relevant API documentation, tutorials, and examples are updated and follow the documentation style guide
PR release notes describe the change in a way relevant to app developers, and are capitalized, punctuated, and past tense.

Release Notes

Notes: Added webFrameMain.printToPDF() to allow printing individual frames to PDF from the main process.

jkleinsc

Conceptually API LGTM, but we should use a structure for the print options since it is reused.

samuelmaddock · 2026-07-24T15:59:08Z

-    })
-    .catch(() => {});
-  return next;
+  return printToPDF(this, options);


Could we simplify PrintToPDFTarget by always directing to the frame-level API?

Suggested change

return printToPDF(this, options);

return this.mainFrame.printToPDF(options);

It's not quite equivalent. WebContents::PrintToPDF doesn't print the primary main frame, it prints GetRenderFrameHostToUse(web_contents()) (printing_utils.cc:111) which redirects to the PDF plugin child frame when the contents is showing the PDF viewer (OOPIF or full-page plugin) and to the focused frame if it has a selection. Routing through this.mainFrame would drop that, so printToPDF() on a loaded .pdf would print the extension embedder page instead of the document. And I don't think we want that redirect inside WebFrameMain::PrintToPDF since a frame-scoped API should print the frame you asked for.

That's why both entry points funnel into printToPDF(target, options) on the JS side and PrintFrameToPDF(rfh, settings) in C++. PrintToPDFTarget is just the shim so the option translation + queueing isn't duplicated.

Makes sense and I do like that both are able to reuse the JS printToPDF method.

If my understanding is correct, an <iframe> embedding a PDF would not return the actual PDF's byte data in the result of frame.printToPDF. I'm a little confused about what the behavior might be which may imply it'd be worth adding a test to confirm expectations. An explicit call out in the docs might also be worth clarifying.

Unlike webContents.printToPDF, this method prints only the contents of the frame it is called on.

If this already implies the expected behavior to what I mentioned above, then maybe that's fine too.

printToPDF on an iframe with a PDF would print the PDF but in a scroll container. You'd need to do frameWithPDF.frames[0] basically to get the actual PDF iframe

jkleinsc

API LGTM

ckerr

API LGTM

ckerr · 2026-07-24T21:28:16Z

I think the macos-arm64 CI failure here is unrelated to this PR, I think it's the same bug being addressed by #52448. If we land that first and then rebase here, it should go green.

ckerr · 2026-07-27T18:45:23Z

rebasing to origin/main now that 52448 has landed

ckerr · 2026-07-28T00:38:06Z

API ReviewStarted 5 hours ago — Pending (2/2 LGTMs - ready on 2026-07-24)

🤔

ckerr

Needs an update to address merge conflicts

Also, not sure what's going on with the API Review bot, which thinks this should be ready on 2026-07-24

Allows printing an individual frame (e.g. an <iframe>) to PDF from the main process, rather than only the full page via webContents.printToPDF. The C++ PDF path already operates on a RenderFrameHost, so the core is extracted to shell/browser/printing/print_to_pdf.cc and shared by both entry points. The JS option translation and job queueing move to a shared lib/browser/print-to-pdf.ts; jobs are serialized per frame tree (keyed by the top frame's frameTreeNodeId, which is stable across navigations) because concurrent print jobs within one frame tree conflict in the renderer, while frames in different webContents still print concurrently. Co-Authored-By: Claude <noreply@anthropic.com>

Co-Authored-By: Claude <noreply@anthropic.com>

The options table was duplicated across webContents, <webview>, and now webFrameMain. Pull it into a PrintToPDFOptions structure and give its margins their own PrintToPDFMargins structure so the generated typings no longer merge them with webContents.print()'s pixel-based Margins. No-Verification-Needed: docs-only

rebased

trop · 2026-08-03T22:15:55Z

I was unable to backport this PR to "42-x-y" cleanly;
you will need to perform this backport manually.

trop · 2026-08-03T22:16:03Z

I was unable to backport this PR to "43-x-y" cleanly;
you will need to perform this backport manually.

trop · 2026-08-03T22:16:46Z

I have automatically backported this PR to "44-x-y", please check out #52625

trop · 2026-08-03T22:37:25Z

@MarshallOfSound has manually backported this PR to "42-x-y", please check out #52626

trop · 2026-08-03T22:37:33Z

@MarshallOfSound has manually backported this PR to "43-x-y", please check out #52627

* feat: add webFrameMain.printToPDF() Allows printing an individual frame (e.g. an <iframe>) to PDF from the main process, rather than only the full page via webContents.printToPDF. The C++ PDF path already operates on a RenderFrameHost, so the core is extracted to shell/browser/printing/print_to_pdf.cc and shared by both entry points. The JS option translation and job queueing move to a shared lib/browser/print-to-pdf.ts; jobs are serialized per frame tree (keyed by the top frame's frameTreeNodeId, which is stable across navigations) because concurrent print jobs within one frame tree conflict in the renderer, while frames in different webContents still print concurrently. * docs: add API history block for webFrameMain.printToPDF() * docs: move printToPDF options into a shared structure The options table was duplicated across webContents, <webview>, and now webFrameMain. Pull it into a PrintToPDFOptions structure and give its margins their own PrintToPDFMargins structure so the generated typings no longer merge them with webContents.print()'s pixel-based Margins. --------- (cherry picked from commit b65f0f2)

feat: add webFrameMain.printToPDF() (#52439) * feat: add webFrameMain.printToPDF() Allows printing an individual frame (e.g. an <iframe>) to PDF from the main process, rather than only the full page via webContents.printToPDF. The C++ PDF path already operates on a RenderFrameHost, so the core is extracted to shell/browser/printing/print_to_pdf.cc and shared by both entry points. The JS option translation and job queueing move to a shared lib/browser/print-to-pdf.ts; jobs are serialized per frame tree (keyed by the top frame's frameTreeNodeId, which is stable across navigations) because concurrent print jobs within one frame tree conflict in the renderer, while frames in different webContents still print concurrently. * docs: add API history block for webFrameMain.printToPDF() * docs: move printToPDF options into a shared structure The options table was duplicated across webContents, <webview>, and now webFrameMain. Pull it into a PrintToPDFOptions structure and give its margins their own PrintToPDFMargins structure so the generated typings no longer merge them with webContents.print()'s pixel-based Margins. --------- (cherry picked from commit b65f0f2)

electron-cation Bot added the new-pr 🌱 PR opened recently label Jul 24, 2026

electron-cation Bot added the api-review/requested 🗳 label Jul 24, 2026

jkleinsc requested changes Jul 24, 2026

View reviewed changes

Comment thread docs/api/web-frame-main.md

samuelmaddock reviewed Jul 24, 2026

View reviewed changes

jkleinsc approved these changes Jul 24, 2026

View reviewed changes

ckerr approved these changes Jul 24, 2026

View reviewed changes

ckerr force-pushed the feat/web-frame-main-print-to-pdf branch from 68e8c8b to 1379418 Compare July 27, 2026 18:45

jkleinsc added the api-review/skip-delay ⏰ Skip the mandatory 7 day waiting period for new APIs label Jul 27, 2026

ckerr closed this Jul 29, 2026

ckerr reopened this Jul 29, 2026

ckerr previously requested changes Jul 29, 2026

View reviewed changes

electron-cation Bot added api-review/approved ✅ and removed new-pr 🌱 PR opened recently api-review/requested 🗳 labels Jul 31, 2026

MarshallOfSound and others added 3 commits August 3, 2026 17:54

docs: add API history block for webFrameMain.printToPDF()

7b9e406

Co-Authored-By: Claude <noreply@anthropic.com>

MarshallOfSound force-pushed the feat/web-frame-main-print-to-pdf branch from 1379418 to 289da56 Compare August 3, 2026 17:55

jkleinsc approved these changes Aug 3, 2026

View reviewed changes

MarshallOfSound merged commit b65f0f2 into main Aug 3, 2026
168 of 174 checks passed

github-actions Bot added the 45-x-y label Aug 3, 2026

trop Bot added needs-manual-bp/42-x-y needs-manual-bp/43-x-y and removed target/42-x-y PR should also be added to the "42-x-y" branch. target/43-x-y PR should also be added to the "43-x-y" branch. labels Aug 3, 2026

trop Bot mentioned this pull request Aug 3, 2026

feat: add webFrameMain.printToPDF() #52625

Merged

trop Bot added in-flight/44-x-y and removed target/44-x-y PR should also be added to the "44-x-y" branch. labels Aug 3, 2026

This was referenced Aug 3, 2026

feat: add webFrameMain.printToPDF() #52626

Merged

feat: add webFrameMain.printToPDF() #52627

Merged

trop Bot added in-flight/42-x-y in-flight/43-x-y and removed needs-manual-bp/42-x-y needs-manual-bp/43-x-y labels Aug 3, 2026

trop Bot added merged/44-x-y PR was merged to the "44-x-y" branch. and removed in-flight/44-x-y labels Aug 5, 2026

trop Bot added merged/42-x-y PR was merged to the "42-x-y" branch. and removed in-flight/42-x-y labels Aug 5, 2026

trop Bot added merged/43-x-y PR was merged to the "43-x-y" branch. and removed in-flight/43-x-y labels Aug 5, 2026

codebytere mentioned this pull request Aug 21, 2026

refactor: resolve webContents.print() settings in the browser process #53083

Open

7 tasks done

electron-release-board Bot added this to 45-x-y Aug 28, 2026

	return printToPDF(this, options);
	return this.mainFrame.printToPDF(options);

Conversation

MarshallOfSound commented Jul 24, 2026 • edited by samuelmaddock Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description of Change

Checklist

Release Notes

Uh oh!

jkleinsc left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

samuelmaddock Jul 24, 2026

Choose a reason for hiding this comment

Uh oh!

MarshallOfSound Jul 24, 2026

Choose a reason for hiding this comment

Uh oh!

samuelmaddock Jul 24, 2026

Choose a reason for hiding this comment

Uh oh!

MarshallOfSound Jul 27, 2026

Choose a reason for hiding this comment

Uh oh!

jkleinsc left a comment

Choose a reason for hiding this comment

Uh oh!

ckerr left a comment

Choose a reason for hiding this comment

Uh oh!

ckerr commented Jul 24, 2026

Uh oh!

ckerr commented Jul 27, 2026

Uh oh!

ckerr commented Jul 28, 2026

Uh oh!

ckerr left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

trop Bot commented Aug 3, 2026

Uh oh!

trop Bot commented Aug 3, 2026

Uh oh!

trop Bot commented Aug 3, 2026

Uh oh!

trop Bot commented Aug 3, 2026

Uh oh!

trop Bot commented Aug 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

MarshallOfSound commented Jul 24, 2026 •

edited by samuelmaddock

Loading