DEV Community

IronSoftware
IronSoftware

Posted on

Why iText 7's API Feels Complex: The Learning Curve

#csharp #dotnet

Developers new to iText 7 often report that the library requires substantial time investment before becoming productive. The modular architecture, low-level PDF access, manual font management, and separate add-ons create a learning curve that contrasts with simpler alternatives. This article examines why developers find iText 7 difficult to use and what architectural decisions contribute to this complexity.

The Problem

iText 7 was designed as a complete PDF manipulation toolkit, giving developers access to both high-level document construction and low-level PDF internals. This flexibility comes at a cost: developers must understand more concepts and write more code to accomplish tasks that competing libraries handle with fewer lines.

The iText team acknowledged this challenge when they rewrote the library. As the original creator noted, "a developer couldn't use my first PDF library without consulting the PDF specification." While iText 7 improved upon earlier versions, the library still exposes significant complexity compared to HTML-based rendering approaches.

Common complaints from developers include:

  • Verbose code for simple document creation
  • Manual management of fonts, streams, and document lifecycle
  • Separate packages required for HTML conversion (pdfHTML)
  • Different classes for creation vs. modification of the same elements
  • Extensive boilerplate code before accomplishing actual tasks

What Developers Experience

Creating a basic document requires understanding the relationship between PdfWriter, PdfDocument, and Document classes:

// iText 7: Creating a simple PDF requires multiple class instantiations
PdfWriter writer = new PdfWriter("output.pdf");
PdfDocument pdfDoc = new PdfDocument(writer);
Document document = new Document(pdfDoc);

// Now you can add content
document.add(new Paragraph("Hello World"));

// Must remember to close to finalize the PDF
document.close();
Enter fullscreen mode Exit fullscreen mode

While this appears straightforward for a "Hello World" example, the code grows substantially when adding common features like custom fonts, tables, or styling.

Who Is Affected

The learning curve impacts several developer profiles:

Developers migrating from iTextSharp (iText 5): The API changed significantly between versions. Classes were renamed, patterns differ, and code that worked in iText 5 requires substantial rewriting. The migration guide itself acknowledges that "the two versions are not backwards compatible."

Teams needing HTML-to-PDF conversion: The base iText 7 package cannot convert HTML to PDF. Teams must add the pdfHTML add-on, learn its separate API, and obtain additional licensing if using the library commercially.

Developers coming from web development: Those familiar with HTML/CSS find iText's programmatic approach unfamiliar. Building a table in iText requires explicit cell creation, colspan handling, and style application through method calls rather than CSS rules.

Time-constrained projects: Teams with deadlines often cannot afford the learning curve investment. As one third-party analysis noted, iText "requires more code for common tasks like text extraction or merging PDFs."

The Complexity in Detail

Multiple Packages and Add-ons

iText 7's modular architecture splits functionality across separate NuGet packages and Maven artifacts:

Package Purpose
itext.kernel Core PDF manipulation
itext.layout Document layout elements
itext.io Input/output operations
itext.forms PDF form handling
itext.pdfhtml HTML to PDF conversion (separate add-on)
itext.pdfsweep Redaction (separate add-on)
itext.pdfocr OCR functionality (separate add-on)

A developer noted that "it is very difficult for the developer to manage so many DLLs." While iText promotes this as "pay only for what you use," in practice teams often need multiple packages and must coordinate their versions.

Font Management Complexity

Font handling in iText 7 illustrates the level of detail developers must manage:

// iText 7: Loading and using a custom font
// Must handle font creation, encoding, and embedding explicitly
PdfFont font = PdfFontFactory.CreateFont(
    "fonts/OpenSans-Regular.ttf",
    PdfEncodings.IDENTITY_H,
    PdfFontFactory.EmbeddingStrategy.FORCE_EMBEDDED
);

// Font must be explicitly applied to elements
Paragraph para = new Paragraph("Styled text")
    .SetFont(font)
    .SetFontSize(12);
Enter fullscreen mode Exit fullscreen mode

Font embedding rules add further complexity. According to iText documentation, "iText will always try to embed a subset of the font, not the whole font" and certain fonts "cannot be embedded due to licensing restrictions." Developers must understand PDF font embedding rules to predict behavior.

When merging documents, "different subsets of the same font will be copied as separate objects" and "iText can't merge different subsets of the same font into one font." This creates unexpected file size growth.

Table Construction Verbosity

Tables demonstrate how iText 7 requires explicit construction of every element:

// iText 7: Creating a table with headers and styling
Table table = new Table(UnitValue.CreatePercentArray(new float[] { 1, 2, 1 }))
    .SetWidth(UnitValue.CreatePercentValue(100));

// Header cells require explicit creation and styling
Cell headerCell1 = new Cell()
    .Add(new Paragraph("ID"))
    .SetBackgroundColor(ColorConstants.LIGHT_GRAY)
    .SetTextAlignment(TextAlignment.CENTER)
    .SetBold();
table.AddHeaderCell(headerCell1);

Cell headerCell2 = new Cell()
    .Add(new Paragraph("Name"))
    .SetBackgroundColor(ColorConstants.LIGHT_GRAY)
    .SetTextAlignment(TextAlignment.CENTER)
    .SetBold();
table.AddHeaderCell(headerCell2);

Cell headerCell3 = new Cell()
    .Add(new Paragraph("Price"))
    .SetBackgroundColor(ColorConstants.LIGHT_GRAY)
    .SetTextAlignment(TextAlignment.CENTER)
    .SetBold();
table.AddHeaderCell(headerCell3);

// Data rows require same explicit construction
table.AddCell(new Cell().Add(new Paragraph("001")));
table.AddCell(new Cell().Add(new Paragraph("Widget")));
table.AddCell(new Cell().Add(new Paragraph("$10.00")));

document.Add(table);
Enter fullscreen mode Exit fullscreen mode

Compare this to the equivalent HTML:

<table style="width:100%">
    <tr>
        <th style="background:#eee; text-align:center">ID</th>
        <th style="background:#eee; text-align:center">Name</th>
        <th style="background:#eee; text-align:center">Price</th>
    </tr>
    <tr>
        <td>001</td>
        <td>Widget</td>
        <td>$10.00</td>
    </tr>
</table>
Enter fullscreen mode Exit fullscreen mode

HTML Conversion Requires Separate Add-on

The pdfHTML add-on for HTML-to-PDF conversion is not included with iText Core. As documented in iText's own materials, developers need to:

  1. Install the separate itext.pdfhtml package
  2. Learn the ConverterProperties API
  3. Handle font providers for non-standard fonts
  4. Manage resource resolution for CSS and images 
// iText pdfHTML: HTML conversion requires separate package and configuration
ConverterProperties converterProperties = new ConverterProperties();

// Custom font handling requires FontProvider setup
FontProvider fontProvider = new DefaultFontProvider(false, false, false);
fontProvider.AddFont("fonts/OpenSans-Regular.ttf");
converterProperties.SetFontProvider(fontProvider);

// Set base URI for resource resolution
converterProperties.SetBaseUri("https://example.com/");

// Convert HTML string to PDF
HtmlConverter.ConvertToPdf(htmlContent, new FileStream("output.pdf", FileMode.Create),
    converterProperties);
Enter fullscreen mode Exit fullscreen mode

Developer Community Feedback

The learning curve has generated significant discussion. Stack Overflow hosts over 1,000 questions specifically about iText usage, prompting the original developer to compile these into a published book.

Third-party comparisons have noted:

"iText 7 has long been a go-to library for PDF handling, but its complex syntax and steep learning curve can slow down development."

"iText requires explicit iteration through PDF pages and manual extraction of text using its PdfTextExtractor, which involves managing PDF document objects and extracting text from each page individually."

"There is a lot of boilerplate code that one needs to write to get going."

The iText team's own documentation uses phrases like "boilerplate code" when describing setup requirements, acknowledging the setup overhead developers encounter.

Root Cause Analysis

Several architectural decisions explain iText 7's complexity:

PDF-first design: iText exposes PDF internals because advanced users need that access. This means all developers encounter the complexity even for simple tasks.

Backwards compatibility concerns: Supporting features from iText 5 while improving the architecture led to layered abstractions that developers must navigate.

Java-first development: iText was designed for Java, then ported to .NET. Some patterns feel more natural in Java than C#, and the API reflects Java conventions.

Commercial/open-source split: Features like pdfHTML are separate add-ons rather than integrated capabilities, creating module management overhead.

Extensibility over simplicity: The architecture prioritizes customization points for advanced use cases, making the common cases more verbose.

A Different Approach: IronPDF

For developers whose primary need is generating PDFs from HTML templates or web content, an HTML-centric approach can dramatically reduce code complexity.

IronPDF takes a fundamentally different approach: instead of building documents programmatically from PDF primitives, it renders HTML using an embedded Chromium browser engine. Developers use familiar HTML and CSS skills, and the complexity of PDF generation is abstracted away.

Why This Approach Requires Less Code

The same table that required 20+ lines in iText becomes a single HTML string:

using IronPdf;

public class InvoiceGenerator
{
    public void GenerateInvoice()
    {
        var renderer = new ChromePdfRenderer();

        // Use HTML/CSS skills you already have
        string html = @"
            <!DOCTYPE html>
            <html>
            <head>
                <style>
                    body { font-family: 'Segoe UI', Arial, sans-serif; }
                    table { width: 100%; border-collapse: collapse; margin-top: 20px; }
                    th { background: #f0f0f0; text-align: center; padding: 10px; }
                    td { border: 1px solid #ddd; padding: 8px; }
                    .total { font-weight: bold; background: #fafafa; }
                </style>
            </head>
            <body>
                <h1>Invoice #12345</h1>
                <table>
                    <tr>
                        <th>ID</th>
                        <th>Product</th>
                        <th>Price</th>
                    </tr>
                    <tr>
                        <td>001</td>
                        <td>Widget A</td>
                        <td>$10.00</td>
                    </tr>
                    <tr>
                        <td>002</td>
                        <td>Widget B</td>
                        <td>$25.00</td>
                    </tr>
                    <tr class='total'>
                        <td colspan='2'>Total</td>
                        <td>$35.00</td>
                    </tr>
                </table>
            </body>
            </html>";

        // One method call converts to PDF
        var pdf = renderer.RenderHtmlAsPdf(html);
        pdf.SaveAs("invoice.pdf");
    }
}
Enter fullscreen mode Exit fullscreen mode

Key differences from iText:

  • No separate packages for HTML conversion (included in base IronPDF)
  • No font provider configuration (system fonts work automatically)
  • No document lifecycle management (no PdfWriter/PdfDocument/Document chain)
  • CSS styling instead of method chaining for appearance
  • Familiar HTML structure instead of learning PDF element classes

Code Comparison: Common Tasks

Creating a styled document:

iText 7:

PdfWriter writer = new PdfWriter("output.pdf");
PdfDocument pdfDoc = new PdfDocument(writer);
Document document = new Document(pdfDoc);
PdfFont font = PdfFontFactory.CreateFont(StandardFonts.HELVETICA);
Paragraph p = new Paragraph("Hello World")
    .SetFont(font)
    .SetFontSize(16)
    .SetFontColor(ColorConstants.BLUE);
document.Add(p);
document.Close();
Enter fullscreen mode Exit fullscreen mode

IronPDF:

var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf(
    "<p style='font-size:16px; color:blue; font-family:Helvetica'>Hello World</p>"
);
pdf.SaveAs("output.pdf");
Enter fullscreen mode Exit fullscreen mode

Converting a URL to PDF:

iText 7 (requires pdfHTML add-on):

// Not directly supported - must fetch HTML first, then convert
// Requires additional HTTP client code and resource handling
Enter fullscreen mode Exit fullscreen mode

IronPDF:

var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderUrlAsPdf("https://example.com/report");
pdf.SaveAs("report.pdf");
Enter fullscreen mode Exit fullscreen mode

API Reference

For more details on the methods used:

Migration Considerations

When iText Makes Sense

iText 7 remains appropriate for:

  • Deep PDF manipulation requiring low-level access
  • Digitally signing PDFs with complex certificate handling
  • PDF/A compliance with specific archival requirements
  • Teams with existing iText expertise and codebases

When IronPDF Makes Sense

IronPDF is typically a better fit when:

  • Documents are generated from templates (invoices, reports, receipts)
  • HTML/CSS skills exist on the team
  • Reduced development time is a priority
  • Cross-platform deployment is required (Windows, Linux, macOS)
  • Modern CSS features like Flexbox and Grid are needed

Licensing

IronPDF uses a commercial license with published pricing. No AGPL considerations apply. Free trial available for evaluation.

For pricing: IronPDF Licensing

API Differences

Migration from iText 7 to IronPDF involves different paradigms:

iText 7 Approach IronPDF Approach
Programmatic element construction HTML templates
PdfFontFactory for fonts System fonts or CSS @font-face
Cell/Table objects HTML tables with CSS
Separate pdfHTML package Built-in HTML rendering
ConverterProperties RenderingOptions

What You Gain

  • Reduced code volume for most document generation tasks
  • Familiar web development patterns
  • Single package with HTML conversion included
  • No font provider configuration
  • JavaScript execution for dynamic content

What to Consider

  • Different approach requires rethinking document generation patterns
  • Low-level PDF manipulation APIs differ from iText
  • Commercial licensing required for production
  • Embedded Chromium increases deployment size (~50MB)

Conclusion

iText 7's complexity stems from its design as a complete PDF toolkit with both high-level and low-level capabilities. For developers whose needs center on document generation from templates, this power becomes overhead. The separate pdfHTML add-on, manual font management, verbose element construction, and multi-package architecture create a learning curve that simpler alternatives avoid.

Teams prioritizing development velocity for template-based document generation may find an HTML-centric approach through IronPDF reduces both code volume and time to productivity.

Written by Jacob Mellor, CTO at Iron Software with 25+ years building developer tools.

References

  1. iText 7 Jump-Start Tutorial - Chapter 1{:rel="nofollow"} - Official introduction to basic building blocks
  2. iText 7 and iText 5: Roadmaps, Differences, Updates{:rel="nofollow"} - Official comparison between versions
  3. iText Fonts Tutorial{:rel="nofollow"} - Font handling comparison between iText versions
  4. iText pdfHTML Product Page{:rel="nofollow"} - Separate HTML conversion add-on documentation
  5. Best iText 7 Questions on StackOverflow{:rel="nofollow"} - Collection of common developer questions
  6. iText vs IronPDF Comparison{:rel="nofollow"} - Third-party feature comparison
  7. Migration Guide from iText 5 to iText 7{:rel="nofollow"} - Official migration documentation
  8. Chapter 6: Using Fonts in pdfHTML{:rel="nofollow"} - Font configuration for HTML conversion
  9. iText Table Examples{:rel="nofollow"} - Official table creation examples
  10. iTextShartp vs IronPDF Comparison - DEV Community{:rel="nofollow"} - Developer perspective on library differences

For the latest IronPDF documentation and tutorials, visit ironpdf.com.

Top comments (0)