Package selection guidance compiled from public package information, community data, and project usage.
pdf_combiner is a lightweight and efficient Flutter plugin that enables seamless merging of multiple PDF documents into a single file. Designed for simplicity and performance, it supports all major platforms including Android, iOS, Web, macOS, Windows, and Linux. The plugin provides a straightforward API to combine PDFs without requiring external dependencies or complex setup. Ideal for apps needing dynamic PDF generation or document consolidation.
Use cases
Merging scanned documents
Creating consolidated reports
Combining user-generated PDFs
Automating document workflows
Building PDF-based content managers
Key features
Cross-platform support
Simple API for merging PDFs
Lightweight and fast
No external dependencies
Supports all major operating systems
Suitable for
Document management apps
Educational tools
Business reporting software
PDF automation workflows
Mobile and desktop applications
Considerations
Requires valid PDF input files
Limited to merging; no editing features
File size may impact performance
Not suitable for complex PDF manipulation
Depends on underlying Dart PDF libraries
Original README
Original README snapshot from the linked source repository. Visit the repository for the latest content.
PDF Combiner
Overview
PDF Combiner is a Flutter plugin designed for combining and manipulating PDF files. It supports multiple platforms including Android, iOS, Linux, macOS, Windows and web, enabling users to:
Combine any number of PDFs and images, in any order, into a single PDF.
Merge multiple PDF files.
Create PDFs from images.
Extract images from PDFs.
Underlying Technologies
Android: PDF manipulation is done natively using android.graphics with Kotlin and PDFBox from Apache but only for merge PDF files.
iOS and macOS: PDF manipulation is done natively using Swift, with no external dependencies.
Linux and Windows: Employs PDFium from Google, a C++ library.
Web: Implements PDFLib in JavaScript for PDF manipulation.
Supported Platforms
This plugin supports Android, iOS, Linux, macOS and web directly, no additional setup is required.
Supported Image Formats
The plugin supports the following image formats:
JPEG
PNG
HEIC
Use HEIF on Linux
To use HEIF images on Linux, you need to install the libheif-dev library.
sudo apt-get install libheif-dev
Features
MergeInput
The MergeInput class is a Dart 3 sealed class representing the input source for PDF operations. It provides type safety and pattern matching support with three concrete implementations:
PathMergeInput (via MergeInput.path)
BytesMergeInput (via MergeInput.bytes)
UrlMergeInput (via MergeInput.url)
Creating from a file path:
final input = MergeInput.path("path/to/file.pdf");
Creating from bytes:
finalUint8List fileBytes = awaitgetFileBytes(); // Your method to get bytesfinal input = MergeInput.bytes(fileBytes);
Creating from a remote URL:
final input = MergeInput.url("https://example.com/file.pdf");
Mixing paths, bytes, and URLs:
You can mix all three approaches in the same list, allowing you to combine files from disk, memory, or remote URLs in a single operation:
final inputs = [
MergeInput.path("path/to/local_file.pdf"),
MergeInput.bytes(fileBytes),
MergeInput.url("https://example.com/remote_file.pdf"),
];
This flexibility is useful when dealing with multiple sources (e.g., local files, dynamically generated charts/images in memory, and remote resources).
Pattern Matching with sealed class
Since MergeInput is a sealed class, you can leverage Dart 3 pattern matching to safely handle the different input types:
switch (input) {
casePathMergeInput(path: final p):
print("Local file path: $p");
caseBytesMergeInput(bytes: final b):
print("In-memory bytes size: ${b.length}");
caseUrlMergeInput(url: final u):
print("Remote URL: $u");
}
[!WARNING]
CORS Restrictions on Web: When using MergeInput.url on the Web platform, the browser will attempt to download the file using fetch. If the hosting server does not configure appropriate CORS headers (Cross-Origin Resource Sharing), the request will fail. Ensure your remote server allows origin-specific requests or download the file as bytes using a backend proxy before passing it as a MergeInput.bytes.
Create PDF From Multiple Documents
Combine any number of PDFs and images, in any order, into a single PDF document.
Required Parameters:
inputs: A list of MergeInput objects representing the image and PDF files (either as paths or bytes).
outputPath: A string representing the absolute path of the file where the generated PDF should be saved. In the case of web, this parameter is ignored. The file extension must be .pdf.
finalUint8List fileBytes = awaitgetFileBytes();
final inputs = [
MergeInput.path("path/to/local_image.jpg"),
MergeInput.bytes(fileBytes),
MergeInput.path("path/to/local_document.pdf"),
];
final outputPath = "path/to/output.pdf";
try {
String response = awaitPdfCombiner.generatePDFFromDocuments(
inputs: inputs,
outputPath: outputPath,
);
print("File saved to: $response");
} catch (e) {
// If the error is handled by the plugin, a PdfCombinerException is thrown.print("Error: $e");
}
Merge Multiple PDFs
Combine several PDF files into a single document.
Required Parameters:
inputs: A list of MergeInput objects representing the PDF files to combine (either as paths or bytes).
outputPath: A string representing the absolute path of the file where the combined PDF should be saved. In the case of web, this parameter is ignored. The file extension must be .pdf.
finalUint8List fileBytes = awaitgetFileBytes();
final inputs = [
MergeInput.path("path/to/local_file1.pdf"),
MergeInput.bytes(fileBytes),
MergeInput.path("path/to/local_file2.pdf"),
];
final outputPath = "path/to/output.pdf";
try {
String response = awaitPdfCombiner.mergeMultiplePDFs(
inputs: inputs,
outputPath: outputPath,
);
print("File saved to: $response");
} catch (e) {
// If the error is handled by the plugin, a PdfCombinerException is thrown.print("Error: $e");
}
Create PDF From Multiple Images
Convert a list of image files into a single PDF document.
Required Parameters:
inputs: A list of MergeInput objects representing the image files (either as paths or bytes).
outputPath: A string representing the absolute path of the file where the generated PDF should be saved. In the case of web, this parameter is ignored. The file extension must be .pdf.
By default, images are added to the PDF without modifications. If needed, you can customize the scaling, compression, and aspect ratio using a configuration object.
finalUint8List fileBytes = awaitgetFileBytes();
final inputs = [
MergeInput.path("path/to/local_image1.jpg"),
MergeInput.bytes(fileBytes),
MergeInput.path("path/to/local_image2.png"),
];
final outputPath = "path/to/output.pdf";
try {
String response = awaitPdfCombiner.createPDFFromMultipleImages(
inputs: inputs,
outputPath: outputPath,
);
print("File saved to: $response");
} catch (e) {
// If the error is handled by the plugin, a PdfCombinerException is thrown.print("Error: $e");
}
Custom Creation of PDF From Multiple Images
The PdfFromMultipleImageConfig class is used to configure how images are processed before creating a PDF.
Parameters:
rescale (default: ImageScale.original): Defines the scaling configuration for the images.
keepAspectRatio (default: true): Ensures that the aspect ratio of the images is preserved when scaling.
Example Usage:
final inputs = [
MergeInput.path("path/to/image1.jpg"),
MergeInput.path("path/to/image2.jpg"),
];
final outputPath = "path/to/output.pdf";
try {
String response = awaitPdfCombiner.createPDFFromMultipleImages(
inputs: inputs,
outputPath: outputPath,
config: constPdfFromMultipleImageConfig(
rescale: ImageScale(width: 480, height: 640),
keepAspectRatio: true,
),
);
print("File saved to: $response");
} catch (e) {
// If the error is handled by the plugin, a PdfCombinerException is thrown.print("Error: $e");
}
Create Images From PDF
Extract images from a PDF file.
Required Parameters:
input: A MergeInput object representing the PDF file (either as a path or bytes).
outputDirPath: A string representing the directory folder where the extracted images should be saved. In the case of web, this parameter is ignored.
By default, images are extracted in their original format. If needed, you can customize the scaling, compression, and aspect ratio using a configuration object.
final input = MergeInput.path("path/to/input.pdf");
// Or from bytes: final input = MergeInput.bytes(fileBytes);final outputDirPath = "path/to/output";
try {
List<String> response = awaitPdfCombiner.createImageFromPDF(
input: input,
outputDirPath: outputDirPath,
);
print("Files generated: $response");
} catch (e) {
// If the error is handled by the plugin, a PdfCombinerException is thrown.print("Error: $e");
}
Custom Creation of Images From PDF
The ImageFromPdfConfig class is used to configure how images are processed before creating a list of images.
Parameters:
rescale (default: ImageScale.original): Defines the scaling configuration for the images.
compression (default: ImageCompression.none): Sets the compression level for image, affecting file size quality and clarity.
createOneImage (default: false): If you want to create a single image with all pages of the PDF or if you want one image per page.
Example Usage:
final input = MergeInput.path("path/to/input.pdf");
final outputDirPath = "path/to/output";
try {
List<String> response = awaitPdfCombiner.createImageFromPDF(
input: input,
outputDirPath: outputDirPath,
config: constImageFromPdfConfig(
rescale: ImageScale(width: 480, height: 640),
compression: ImageCompression.custom(35),
createOneImage: true,
),
);
print("Files generated: $response");
} catch (e) {
// If the error is handled by the plugin, a PdfCombinerException is thrown.print("Error: $e");
}
ImageCompression
Represents the compression level of an image, affecting quality and file size.
Predefined Compression Levels
The ImageCompression class provides three predefined quality levels:
ImageCompression.none (0) → No compression, highest quality, largest file size. (The default).
ImageCompression.medium (60) → Balanced compression and image clarity.
ImageCompression.high (100) → High compression, lower quality, smaller file size.
ImageCompression.custom(int value) → Allows for custom quality levels between 1 and 100.
Summary of Supported Cases
Compression Level
Value Range
Example Usage
None
0
ImageCompression.none
Low
30
ImageCompression.low
Medium
60
ImageCompression.medium
High
100
ImageCompression.high
Custom
1 - 100
ImageCompression.custom(75)
Example Usage:
final compression = ImageCompression.medium;
print(compression.value); // Output: 60
PdfCombinerException
When an error occurs during an operation, such as a file not being found, an invalid format, or an internal error in PDF processing, the plugin throws a PdfCombinerException.
This exception contains:
message: A descriptive message about what went wrong.
You can handle it explicitly if you need more control:
This plugin works with file_picker or image_picker for selecting files. Ensure you handle permissions using permission_handler before invoking the plugin.
Dependencies
The pdf_combiner plugin does not directly use the following dependencies. They are mentioned only to guide the development of solutions that might require additional steps for file selection or permissions:
This document describes the breaking changes introduced in recent versions of pdf_combiner and how to migrate existing projects safely.
Version 5.0.0 (Breaking Changes)
If you are upgrading to v5.0.0 or later, please review the following breaking changes carefully.
1. Response Models Removed
The following response classes have been removed:
GeneratePdfFromDocumentsResponse
MergeMultiplePDFResponse
PdfFromMultipleImageResponse
ImageFromPDFResponse
The API no longer wraps results in response objects.
2. Primitive Return Types
All public methods now return primitive values instead of custom models:
Future<String> → path to the generated PDF/file
Future<List<String>> → paths to generated files
This makes the API simpler and more idiomatic to Dart.
3. Status & Delegates Removed
The following elements are no longer available:
PdfCombinerStatus
PdfCombinerDelegate
The plugin now relies exclusively on:
Standard Dart Futures
Exceptions for error reporting
4. Error Handling via Exceptions
Instead of checking for status codes, errors are now communicated by throwing a:
PdfCombinerException
Consumers must handle failures using try-catch.
Migration Example
Before (v4.x and earlier)
var response = awaitPdfCombiner.mergeMultiplePDFs(...);
if (response.status == PdfCombinerStatus.success) {
print(response.response);
} else {
print(response.message);
}
After (v5.0.0+)
try {
String path = awaitPdfCombiner.mergeMultiplePDFs(...);
print(path);
} catch (e) {
// If the error is plugin-related, a PdfCombinerException is thrown.print(e);
}
Version 3.3.0+
No manual configuration is required for web projects using this version or newer.
As of version 3.3.0 (Web): The pdf_combiner.js JavaScript file is now loaded dynamically, eliminating the need to manually include it and import it into the index.html file.
Legacy Web Integration (Before v3.3.0)
For versions older than 3.3.0, follow these steps:
Add the required JavaScript file
Download pdf_combiner.js and place it in the web/assets/js folder of your Flutter project.
Include the script in your HTML file
Add the following line to the <head> section of your web/index.html file:
<scriptsrc="assets/js/pdf_combiner.js"></script>
Notes
No additional configuration is required for Android, iOS, or MacOS. Ensure the necessary dependencies for file selection and permissions are added to your project.
Since version 3.3.0, the pdf_combiner.js script is automatically loaded in the web platform, making manual inclusion unnecessary for newer versions.