---
title: "Adding a custom page to a PDF document | Nutrient Java SDK"
canonical_url: "https://www.nutrient.io/guides/java/editor/add-custom-page-to-pdf/"
md_url: "https://www.nutrient.io/guides/java/editor/add-custom-page-to-pdf.md"
last_updated: "2026-06-09T10:32:42.836Z"
description: "How to add a custom page to a PDF using Nutrient Java SDK."
---

# Adding a custom page to a PDF document

Use page insertion to control document structure in generated PDFs.

Common use cases include:

- Inserting invoice cover pages

- Adding divider pages between legal sections

- Appending signature pages to forms

- Inserting note pages in educational documents

- Adding title or section pages in generated reports

This guide shows how to:

- Insert pages at specific positions (zero-based index)

- Define custom page dimensions in points (`1 inch = 72 points`)

- Export the final document as PDF

[Download sample](https://www.nutrient.io/downloads/samples/java/add-custom-page-to-pdf.zip)

## How Nutrient helps

Nutrient Java SDK handles page collection management, insertion, and format conversion.

The SDK handles:

- PDF page structure and internal page tree dictionaries

- Page dimensions and coordinate transformations for different page sizes

- Document format conversion from Word, Excel, and PowerPoint to PDF

- Complex page indexing and insertion position validation

## Complete implementation

This example inserts a custom page and exports the result as PDF:

```java

package io.nutrient.Sample;

import io.nutrient.sdk.Document;
import io.nutrient.sdk.exceptions.NutrientException;
import io.nutrient.sdk.editors.PdfEditor;
import io.nutrient.sdk.editors.pdf.pages.PdfPageCollection;

```

Create the main class and entry point:

```java

public class PDFEditor {
    public static void main(String[] args) throws NutrientException {

```

## Opening a document

Open the source document with try-with-resources so Java closes resources after processing.

In this sample, you open a Word file (`.docx`). The SDK also supports:

- PDF files

- Word binary files (`.doc`)

- PowerPoint files (`.pptx`) and PowerPoint binary files (`.ppt`)

- Excel files (`.xlsx`) and Excel binary files (`.xls`)

- Input streams

```java

        try (Document document = Document.open("input.docx")) {

```

## Creating a PDF editor instance

Create a `PdfEditor` to enable page operations on the opened document:

```java

            PdfEditor editor = PdfEditor.edit(document);

```

## Adding custom pages

Get the page collection and insert a page with `pages.insert(index, width, height)`.

Parameters:

- `index`: zero-based insertion point

- `width`: page width in points

- `height`: page height in points

In this sample:

- `pages.insert(4, 500.0f, 800.0f)` inserts a page at index `4` (fifth position).

- `500.0f × 800.0f` points is a custom page size.

Common page sizes:

- US Letter: `612 × 792` points

- A4: `595 × 842` points

- Legal: `612 × 1008` points

```java

            PdfPageCollection pages = editor.getPageCollection();
            pages.insert(4, 500.0f, 800.0f);

```

## Saving and exporting

Save changes, close the editor, and export the document as PDF:

```java

            editor.save();
            editor.close();

            document.exportAsPdf("output.pdf");
        }
    }
}

```

## Error handling

The Java SDK throws `NutrientException` when document operations fail.

Common failure scenarios include:

- The input file can’t be read due to file system permissions, path errors, or file locking by another process

- Document data is corrupted or uses an unsupported file format, preventing proper parsing

- Insufficient system memory for loading large documents or performing format conversion

- Invalid page insertion index (negative or beyond document bounds) causing index out of range errors

- Invalid page dimensions (zero or negative width/height values) preventing page creation

- PDF export failures due to incompatible document features or encoding issues

In production code:

- Catch `NutrientException`.

- Return a clear error message.

- Log failure details for debugging.

## Conclusion

Use this workflow to add custom pages:

1. Open the source document using try-with-resources for automatic resource cleanup.

2. The SDK supports opening documents from file paths or input streams for different integration scenarios.

3. Supported input formats include Word (`.docx`, `.doc`), PowerPoint (`.pptx`, `.ppt`), Excel (`.xlsx`, `.xls`), and existing PDF documents.

4. Create a PDF editor instance with `PdfEditor.edit()` to enable document manipulation operations.

5. The editor maintains document state throughout the editing session until changes are saved.

6. Retrieve the page collection with `editor.getPageCollection()` to access all document pages.

7. Insert a custom page with `pages.insert()` using three parameters: position index (zero-based), width in points, and height in points.

8. Page dimensions are specified in points where 1 inch = 72 points (e.g. 500 points ≈ 6.94 inches).

9. Standard page sizes include US Letter (612 × 792 points), A4 (595 × 842 points), and Legal (612 × 1008 points).

10. Zero-based indexing means index `0` inserts before the first page, and index `4` becomes the fifth page position.

11. Save editor modifications with `editor.save()` to persist page insertions to the document structure.

12. Close the editor with `editor.close()` to release resources, including memory buffers and temporary data.

13. Export the document as PDF with `document.exportAsPdf()`, which converts the source format with inserted pages.

14. Handle `NutrientException` errors for robust error recovery including invalid indices, dimensions, or file format issues.

For related document workflows, refer to the [Java SDK guides](https://www.nutrient.io/guides/java.md).

Download [this ready-to-use sample package](https://www.nutrient.io/downloads/samples/java/add-custom-page-to-pdf.zip), fully configured to help you explore the page manipulation capabilities.
---

## Related pages

- [Adding annotations to a PDF document](/guides/java/editor/add-annotations-to-pdf.md)
- [Adding interactive form fields to a PDF document](/guides/java/editor/add-form-fields-to-pdf.md)
- [Adding free text annotations to a PDF document](/guides/java/editor/add-freetext-annotations-to-pdf.md)
- [Adding invisible digital signatures to a PDF document](/guides/java/editor/add-invisible-signature-to-pdf.md)
- [Adding link annotations to a PDF document](/guides/java/editor/add-link-annotations-to-pdf.md)
- [Adding redaction annotations to a PDF document](/guides/java/editor/add-redaction-annotations-to-pdf.md)
- [Adding stamp annotations to a PDF document](/guides/java/editor/add-stamp-annotations-to-pdf.md)
- [Adding sticky note annotations to a PDF document](/guides/java/editor/add-sticky-note-annotations-to-pdf.md)
- [Adding shape annotations to a PDF document](/guides/java/editor/add-shape-annotations-to-pdf.md)
- [Adding text markup annotations to a PDF document](/guides/java/editor/add-text-markup-annotations-to-pdf.md)
- [Adding visible digital signatures to a PDF document](/guides/java/editor/add-visible-signature-to-pdf.md)
- [Advanced digital signature workflows](/guides/java/editor/advanced-digital-signatures.md)
- [Detecting and adding form fields to a PDF document](/guides/java/editor/detect-and-add-form-fields.md)
- [Editing PDF form fields](/guides/java/editor/editing-pdf-form-fields.md)
- [Nutrient Java SDK editor guides](/guides/java/editor.md)
- [Editing PDF metadata with Nutrient Java SDK](/guides/java/editor/editing-pdf-metadata.md)
- [Merging PDFs](/guides/java/editor/merge-pdf-into-other-pdf.md)
- [Filling PDF form fields](/guides/java/editor/fill-pdf-form.md)
- [Managing PDF page order](/guides/java/editor/manage-pdf-page-order.md)