Class CompressionOptions

Configuration options for reducing PDF file size through compression. Controls image quality, structural data, and compression algorithms for optimal size/quality balance.

Example - Optimize PDF for different use cases:

// Maximum compression for email/web (smaller file, lower quality):
var webOptions = new CompressionOptions
{
    CompressImages = true,
    ShrinkImages = true,
    JpegQuality = 60,
    HighQualityImageSubsampling = false,
    RemoveStructureTree = true
};
pdf.Compress(webOptions);  // Can reduce 10MB to ~2MB

// Balanced compression for general distribution:
var balancedOptions = new CompressionOptions
{
CompressImages = true,
ShrinkImages = true,
JpegQuality = 80,
HighQualityImageSubsampling = true,
RemoveStructureTree = false  // Preserve text selection
};
pdf.Compress(balancedOptions);


// Quality-first compression for archival:
var archiveOptions = new CompressionOptions
{
CompressImages = true,
ShrinkImages = false,  // Keep original resolution
JpegQuality = 95,
HighQualityImageSubsampling = true,
RemoveStructureTree = false
};
pdf.Compress(archiveOptions);

Inheritance
System.Object
CompressionOptions
Namespace: IronPdf
Assembly: IronPdf.dll
Syntax
public class CompressionOptions : Object

Working with PDF generation in IronPDF runs through CompressionOptions. It represents configuration options for reducing PDF file size through compression.

CompressionOptions matters when an application needs to configure or invoke PDF generation from C# code. The class encapsulates the related options and behavior in a single object that is set up once and reused across render or processing calls. Typical scenarios include batch generation pipelines, templated document workflows, and integration with existing C# document services.

To use CompressionOptions, instantiate or obtain it from the relevant entry point in the IronPDF C# API. Key properties include CompressImages, HighQualityImageSubsampling, JpegQuality, RemoveStructureTree. Assign options or invoke methods on the instance to configure or perform the operation. The stamp text image covers typical usage in C# end to end.

using IronPdf;

var instance = new CompressionOptions();
var current = instance.CompressImages;
// Read or assign other properties such as HighQualityImageSubsampling, JpegQuality

For the broader workflow, see the custom paper size guide in the IronPDF C# documentation. For broader context, the PDF generation portion of the IronPDF C# API contains related types that work with CompressionOptions directly. CompressionOptions exposes additional members beyond those highlighted above; the reference tables on this page list the full set. In application code, treat CompressionOptions as a configured object that is constructed once and reused across operations rather than instantiated per call. Configuration is generally idempotent: assigning the same property value twice has the same effect as assigning it once. For diagnostic purposes, inspect the relevant CompressionOptions property after each operation to confirm the configured state. See the constructors, properties, and methods tables below for the complete API surface of CompressionOptions. Application code typically obtains or instantiates a single CompressionOptions and shares it across multiple IronPDF operations rather than recreating it per call.

Constructors

CompressionOptions()

Declaration
public CompressionOptions()

Properties

CompressImages

Enables JPEG compression for embedded images to reduce file size. Images are re-encoded using the JpegQuality setting (default: true).

Example:

options.CompressImages = true;
options.JpegQuality = 75;  // Use with specific quality

Declaration
public bool CompressImages { get; set; }
Property Value
Type Description
System.Boolean

true to compress images (default); false to preserve original encoding.

HighQualityImageSubsampling

Controls JPEG chroma subsampling quality during image compression. Higher quality preserves color detail, especially in photos and graphics (default: true).

Subsampling modes:

options.HighQualityImageSubsampling = true;   // 4:4:4 - Better color accuracy
options.HighQualityImageSubsampling = false;  // 4:1:1 - Smaller file, some color loss

Declaration
public bool HighQualityImageSubsampling { get; set; }
Property Value
Type Description
System.Boolean

true for 4:4:4 subsampling (default); false for 4:1:1 subsampling.

JpegQuality

JPEG compression quality level for images (1-100). Higher values preserve detail but produce larger files (default: 90).

Recommended settings:

options.JpegQuality = 95;  // Archival - nearly lossless
options.JpegQuality = 85;  // High quality - minimal visible artifacts
options.JpegQuality = 70;  // Balanced - good for general use
options.JpegQuality = 50;  // Web/email - noticeable artifacts, small file
options.JpegQuality = 30;  // Aggressive - significant quality loss

Declaration
public int JpegQuality { get; set; }
Property Value
Type Description
System.Int32

Quality level from 1 (minimum) to 100 (maximum). Default is 90.

RemoveStructureTree

Removes the document structure tree to reduce file size. The structure tree stores logical layout information (headings, paragraphs, reading order).

Can significantly reduce file size for complex documents.

When to keep structure tree:

// Preserve for accessibility and text selection:
options.RemoveStructureTree = false;

// Remove for maximum compression (web uploads):
options.RemoveStructureTree = true;

Declaration
public bool RemoveStructureTree { get; set; }
Property Value
Type Description
System.Boolean

true to remove structure (default); false to preserve accessibility.
Remarks

Removing the structure tree may affect text selection in complex documents and reduces PDF/UA accessibility compliance.

ShrinkImages

Scales down image resolution to match visible display size in the PDF. Dramatically reduces file size for PDFs with oversized source images (default: true).

Example impact:

// A 4000x3000 image displayed at 400x300 in the PDF:
options.ShrinkImages = true;   // Resizes to ~400x300 → Major size reduction
options.ShrinkImages = false;  // Keeps original 4000x3000 → Better for zoom/print

Declaration
public bool ShrinkImages { get; set; }
Property Value
Type Description
System.Boolean

true to shrink images (default); false to preserve original resolution.
Remarks

Set to false if users may need to zoom in on images or print at high quality.

See Also