Printing documents is a common requirement in desktop applications, background services, and server-side systems. In practical development and business scenarios, developers often need to print files silently, route jobs to specific printers, or control printing behavior programmatically—without relying on user interaction.

This guide demonstrates how to use Spire.Printing to implement flexible, automated printing of PDF and Office documents in C# across Windows, Linux, and macOS. You will learn how to handle printable streams, select printers programmatically, and apply advanced print settings, enabling reliable cross-platform printing in modern .NET applications.

Table of Contents

• Installing Spire.Printing
• The Core Printing Workflow and Printing Settings
• Printing Word, Excel, PowerPoint, PDF, and Other Documents
• Advanced Print Settings and Operations
• Licensing Notes

Installing Spire.Printing

Spire.Printing is distributed as a NuGet package and can be added to your project in the standard way:

Install-Package Spire.Printing

Platform Compatibility

Spire.Printing is a cross-platform printing library for modern .NET applications. When used together with Spire.Office libraries (with .NET Standard support), it enables printing Word, Excel, PowerPoint, PDF, and other document formats across Windows, Linux, and macOS—without relying on MS Office Interop.

It supports recent .NET runtimes, including .NET 5.0, .NET 6.0, .NET 9.0, and .NET 10.0, and runs on the following platforms:

• Windows (x64, x86)
• Linux (x64, ARM)
• macOS (x64, ARM)

The Core Printing Workflow and Printing Settings

Spire.Printing is designed to send print-ready document streams directly to the printer. On Windows, the printable stream is typically an XPS document, while on Linux and macOS it is a PDF document. It is commonly used with Spire.Office for .NET to implement the printing workflow in .NET applications.

The general process is:

1. Create an IPrintDocumentStream instance from the document.
2. Create a PrintDocument instance.
3. Configure print settings through the PrintSettings property.
4. Send the job to the printer.

Code Example

using Spire.Printing;

IPrintDocumentStream documentStream;
if (System.Runtime.InteropServices.RuntimeInformation.IsOSPlatform(System.Runtime.InteropServices.OSPlatform.Windows))
{
    // Windows
    documentStream = new XpsPrintDocument("test.xps");
}
else
{
    // Non-Windows(Linux, MacOS)
    documentStream = new PdfPrintDocument("test.pdf");
}
//new PrintDocument
PrintDocument printDocument = new PrintDocument(documentStream);

//Set paper size
printDocument.PrintSettings.PaperSize = PaperSize.A4;

//Set the number of copies to be printed
printDocument.PrintSettings.Copies = 2;

//Select a page range
printDocument.PrintSettings.SelectPageRange(2, 5);

//Duplex Printing
if (printDocument.PrintSettings.CanDuplex)
{
    //Print in duplex
    printDocument.PrintSettings.Duplex = Duplex.Vertical;
}

//Collated vs. uncollated output:
printDocument.PrintSettings.Collate = true;

//Printing a file to a specific printer, if not set, print to the default printer
printDocument.PrintSettings.PrinterName = "Your Printer Name";

// Print to the specified file
printDocument.PrintSettings.PrintToFile("toXps.xps");

//Record printing logs
printDocument.PrintSettings.PrintLogger = new DefaultPrintLogger("log.txt");

//Print
printDocument.Print();

//Dispose
printDocument.Dispose();

This stream-based model keeps the printing workflow consistent across platforms, while allowing all printer behavior to be customized through the PrintSettings API.

Printing Word, Excel, PowerPoint, PDF, and Other Documents

To print Word, Excel, PowerPoint, PDF, and other document types, Spire.Printing is used together with the corresponding Spire.Office document libraries—Spire.Doc, Spire.XLS, Spire.Presentation, and Spire.PDF (especially the .NET Standard version)—to load the source files, save them into IPrintDocumentStream, and send them to the printer.

Printing Word Documents in C#

Library Installation

Install-Package Spire.Printing
Install-Package Spire.Docfor.NETStandard

Code Example

using Spire.Doc;
using Spire.Printing;

//Check the system
bool isWindows = System.Runtime.InteropServices.RuntimeInformation.IsOSPlatform(System.Runtime.InteropServices.OSPlatform.Windows);

using (Document document = new Document())
{
    //Use Spire.Doc to save documents as. xps or. pdf document streams
    document.LoadFromFile(@"test.docx");
    Spire.Doc.FileFormat fileFormat = !isWindows ? Spire.Doc.FileFormat.PDF : Spire.Doc.FileFormat.XPS;
    MemoryStream stream = new MemoryStream();
    document.SaveToStream(stream, fileFormat);

    //Save to IPrintDocumentStream according to the system
    IPrintDocumentStream docStream = !isWindows ? new PdfPrintDocument(stream) : new XpsPrintDocument(stream);

    //Print
    PrintDocument printDoc = new PrintDocument(docStream);
    printDoc.PrintSettings.SelectPageRange(1, 1);
    printDoc.Print();

    //Dispose
    printDoc.Dispose();
}

Printing Excel Files in C#

Library Installation

Install-Package Spire.Printing
Install-Package Spire.XLSfor.NETStandard

Code Example

using Spire.Printing;
using Spire.Xls;

//Check the system
bool isWindows = System.Runtime.InteropServices.RuntimeInformation.IsOSPlatform(System.Runtime.InteropServices.OSPlatform.Windows);
using (Workbook wb = new Workbook())
{
    //Use Spire.Xls to save documents as. xps or. pdf document streams
    wb.LoadFromFile("test.xlsx");
    Spire.Xls.FileFormat fileFormat = !isWindows ? Spire.Xls.FileFormat.PDF : Spire.Xls.FileFormat.XPS;
    MemoryStream stream = new MemoryStream();
    wb.SaveToStream(stream, fileFormat);

    //Save to IPrintDocumentStream according to the system
    IPrintDocumentStream xlsStream = !isWindows ? new PdfPrintDocument(stream) : new XpsPrintDocument(stream);

    //Print
    PrintDocument printxls = new PrintDocument(xlsStream);
    printxls.PrintSettings.SelectPageRange(1, 1);
    printxls.Print();

    //Dispose
    printxls.Dispose();
}

Printing PDF Files in C#

Library Installation

Install-Package Spire.Printing
Install-Package Spire.PDFfor.NETStandard

Code Example

using Spire.Pdf;
using Spire.Printing;

//Check the system
bool isWindows = System.Runtime.InteropServices.RuntimeInformation.IsOSPlatform(System.Runtime.InteropServices.OSPlatform.Windows);
using (PdfDocument pdfDocument = new PdfDocument())
{
    //Use Spire.PDF to save documents as. xps or. pdf document streams
    pdfDocument.LoadFromFile("test.pdf");
    Spire.Pdf.FileFormat fileFormat = !isWindows ? Spire.Pdf.FileFormat.PDF : Spire.Pdf.FileFormat.XPS;
    MemoryStream stream = new MemoryStream();
    pdfDocument.SaveToStream(stream, fileFormat);

    //Save to IPrintDocumentStream according to the system
    IPrintDocumentStream pdfStream = !isWindows ? new PdfPrintDocument(stream) : new XpsPrintDocument(stream);

    //Print
    PrintDocument printPdf = new PrintDocument(pdfStream);
    printPdf.PrintSettings.SelectPageRange(1, 1);
    printPdf.Print();

    //Dispose
    printPdf.Dispose();
}

Printing PowerPoint Presentations in C#

Library Installation

Install-Package Spire.Printing
Install-Package Spire.Presentationfor.NETStandard

Code Example

using Spire.Presentation;
using Spire.Printing;

//Check the system
bool isWindows = System.Runtime.InteropServices.RuntimeInformation.IsOSPlatform(System.Runtime.InteropServices.OSPlatform.Windows);
using (Presentation ppt = new Presentation())
{
    //Use Spire.Presentation to save documents as. xps or. pdf document streams
    ppt.LoadFromFile("test.pptx");
    Spire.Presentation.FileFormat fileFormat = !isWindows ? Spire.Presentation.FileFormat.PDF : Spire.Presentation.FileFormat.XPS;
    MemoryStream stream = new MemoryStream();
    ppt.SaveToFile(stream, fileFormat);

    //Save to IPrintDocumentStream according to the system
    IPrintDocumentStream pptStream = !isWindows ? new PdfPrintDocument(stream) : new XpsPrintDocument(stream);

    //Print
    PrintDocument printPpt = new PrintDocument(pptStream);
    printPpt.PrintSettings.SelectPageRange(1, 1);
    printPpt.Print();

    //Dispose
    printPpt.Dispose();
}

Advanced Print Settings and Operations

For automated and cross-platform printing scenarios, Spire.Printing provides additional control over printer selection, paper handling, and page output through the PrintSettings API. These options are commonly used in unattended services and batch-printing workflows.

Discovering and Selecting a Printer

Instead of using the system default, you can enumerate available printers and route the print job to a specific device:

IEnumerable<string> printers = printDocument.PrintSettings.Printers;

// Select the first printer or choose based on your logic
string selectedPrinterName = printers.First();
printDocument.PrintSettings.PrinterName = selectedPrinterName;

This is useful when multiple printers are installed or when deterministic printer routing is required.

Choosing a Supported Paper Size

To ensure compatibility with the selected printer, you can query and apply one of its supported paper sizes:

IEnumerable<PaperSize> paperSizes = printDocument.PrintSettings.PaperSizes;

// Select the first available size or apply custom logic
PaperSize selectedPaperSize = paperSizes.First();
printDocument.PrintSettings.PaperSize = selectedPaperSize;

This guarantees the selected paper size is compatible with the target printer.

Selecting Specific Pages

You can restrict printing to certain pages, either as a continuous range or a specific set:

// Print pages 2 to 5
printDocument.PrintSettings.SelectPageRange(2, 5);

// Print specific pages: 1, 3, 5, 7
int[] pages = { 1, 3, 5, 7 };
printDocument.PrintSettings.SelectSomePages(pages);

Only one of these methods should be used per print job.

These advanced operations allow precise control over print output, making it suitable for automated workflows, batch processing, or scenarios where consistent print settings are required across multiple documents and printers.

Licensing Notes

Without a valid license, Spire.Printing prints only the first 10 pages. This limitation can be removed by applying a license for Spire.Office for .NET or the corresponding document libraries, such as Spire.Doc, Spire.XLS, Spire.PDF, or Spire.Presentation.

Spire.Pdf.License.LicenseProvider.SetLicenseKey(string key);
Spire.Doc.License.LicenseProvider.SetLicenseKey(string key);
Spire.Xls.License.LicenseProvider.SetLicenseKey(string key);
Spire.Presentation.License.LicenseProvider.SetLicenseKey(string key);

For details on how to apply a license key, see the licensing guide.

Conclusion

Spire.Printing provides a flexible and reliable way to implement professional printing in C# applications. It supports stream-based printing of PDF, Word, Excel, and PowerPoint documents across Windows, Linux, and macOS, and works seamlessly with Spire.Office for .NET libraries—especially for .NET Standard—to handle Office and PDF files in modern .NET applications.

With the core printing workflow understood, developers can easily apply advanced print settings, such as selecting printers, paper sizes, or specific pages, to meet real-world business requirements and automated workflows.

For evaluation or short-term testing scenarios, a temporary license can be requested to remove trial limitations during development.

Creating Word documents programmatically is a common requirement in Python applications. Reports, invoices, contracts, audit logs, and exported datasets are often expected to be delivered as editable .docx files rather than plain text or PDFs.

Unlike plain text output, a Word document is a structured document composed of sections, paragraphs, styles, and layout rules. When generating Word documents in Python, treating .docx files as simple text containers quickly leads to layout issues and maintenance problems.

This tutorial focuses on practical Word document creation in Python using Spire.Doc for Python. It demonstrates how to construct documents using Word’s native object model, apply formatting at the correct structural level, and generate .docx files that remain stable and editable as content grows.

Content Overview

• 1. Understanding Word Document Structure in Python
• 2. Creating a Basic Word Document in Python
• 3. Adding and Formatting Text Content
• 4. Inserting Images into a Word Document
• 5. Creating and Populating Tables
• 6. Adding Headers and Footers
• 7. Controlling Page Layout with Sections
• 8. Setting Document Properties and Metadata
• 9. Saving, Exporting, and Performance Considerations
• 10. Common Pitfalls When Creating Word Documents in Python

1. Understanding Word Document Structure in Python

Before writing code, it is important to understand how a Word document is structured internally.

A .docx file is not a linear stream of text. It consists of multiple object layers, each with a specific responsibility:

• Document – the root container for the entire file
• Section – defines page-level layout such as size, margins, and orientation
• Paragraph – represents a logical block of text
• Run (TextRange) – an inline segment of text with character formatting
• Style – a reusable formatting definition applied to paragraphs or runs

When you create a Word document in Python, you are explicitly constructing this hierarchy in code. Formatting and layout behave predictably only when content is added at the appropriate level.

Spire.Doc for Python provides direct abstractions for these elements, allowing you to work with Word documents in a way that closely mirrors how Word itself organizes content.

2. Creating a Basic Word Document in Python

This section shows how to generate a valid Word document in Python using Spire.Doc. The example focuses on establishing the correct document structure and essential workflow.

Installing Spire.Doc for Python

pip install spire.doc

Alternatively, you can download Spire.Doc for Python and integrate it manually.

Creating a Simple .docx File

from spire.doc import Document, FileFormat

# Create the document container
document = Document()

# Add a section (defines page-level layout)
section = document.AddSection()

# Add a paragraph to the section
paragraph = section.AddParagraph()
paragraph.AppendText(
    "This document was generated using Python. "
    "It demonstrates basic Word document creation with Spire.Doc."
)

# Save the document
document.SaveToFile("basic_document.docx", FileFormat.Docx)
document.Close()

This example creates a minimal but valid .docx file that can be opened in Microsoft Word. It demonstrates the essential workflow: creating a document, adding a section, inserting a paragraph, and saving the file.

From a technical perspective:

• The Document object represents the Word file structure and manages its content.
• The Section defines the page-level layout context for paragraphs.
• The Paragraph contains the visible text and serves as the basic unit for all paragraph-level formatting.

All Word documents generated with Spire.Doc follow this same structural pattern, which forms the foundation for more advanced operations.

3. Adding and Formatting Text Content

Text in a Word document is organized hierarchically. Formatting can be applied at the paragraph level (controlling alignment, spacing, indentation, etc.) or the character level (controlling font, size, color, bold, italic, etc.). Styles provide a convenient way to store these formatting settings so they can be consistently applied to multiple paragraphs or text ranges without redefining the formatting each time. Understanding the distinction between paragraph formatting, character formatting, and styles is essential when creating or editing Word documents in Python.

Adding and Setting Paragraph Formatting

All visible text in a Word document must be added through paragraphs, which serve as containers for text and layout. Paragraph-level formatting controls alignment, spacing, and indentation, and can be set directly via the Paragraph.Format property. Character-level formatting, such as font size, bold, or color, can be applied to text ranges within the paragraph via the TextRange.CharacterFormat property.

from spire.doc import Document, HorizontalAlignment, FileFormat, Color

document = Document()
section = document.AddSection()

# Add the title paragraph
title = section.AddParagraph()
title.Format.HorizontalAlignment = HorizontalAlignment.Center
title.Format.AfterSpacing = 20  # Space after the title
title.Format.BeforeSpacing = 20
title_range = title.AppendText("Monthly Sales Report")
title_range.CharacterFormat.FontSize = 18
title_range.CharacterFormat.Bold = True
title_range.CharacterFormat.TextColor = Color.get_LightBlue()

# Add the body paragraph
body = section.AddParagraph()
body.Format.FirstLineIndent = 20
body_range = body.AppendText(
    "This report provides an overview of monthly sales performance, "
    "including revenue trends across different regions and product categories. "
    "The data presented below is intended to support management decision-making."
)
body_range.CharacterFormat.FontSize = 12

# Save the document
document.SaveToFile("formatted_paragraph.docx", FileFormat.Docx)
document.Close()

Below is a preview of the generated Word document.

Technical notes

• Paragraph.Format sets alignment, spacing, and indentation for the entire paragraph
• AppendText() returns a TextRange object, which allows character-level formatting (font size, bold, color)
• Every paragraph must belong to a section, and paragraph order determines reading flow and pagination

Creating and Applying Styles

Styles allow you to define paragraph-level and character-level formatting once and reuse it across the document. They can store alignment, spacing, font, and text emphasis, making formatting more consistent and easier to maintain. Word documents support both custom styles and built-in styles, which must be added to the document before being applied.

Creating and Applying a Custom Paragraph Style

from spire.doc import (
    Document, HorizontalAlignment, BuiltinStyle,
    TextAlignment, ParagraphStyle, FileFormat
)

document = Document()

# Create a new custom paragraph style
custom_style = ParagraphStyle(document)
custom_style.Name = "CustomStyle"
custom_style.ParagraphFormat.HorizontalAlignment = HorizontalAlignment.Center
custom_style.ParagraphFormat.TextAlignment = TextAlignment.Auto
custom_style.CharacterFormat.Bold = True
custom_style.CharacterFormat.FontSize = 20

# Inherit properties from a built-in heading style
custom_style.ApplyBaseStyle(BuiltinStyle.Heading1)

# Add the style to the document
document.Styles.Add(custom_style)

# Apply the custom style
title_para = document.AddSection().AddParagraph()
title_para.ApplyStyle(custom_style.Name)
title_para.AppendText("Regional Performance Overview")

Adding and Applying Built-in Styles

# Add a built-in style to the document
built_in_style = document.AddStyle(BuiltinStyle.Heading2)
document.Styles.Add(built_in_style)

# Apply the built-in style
heading_para = document.Sections.get_Item(0).AddParagraph()
heading_para.ApplyStyle(built_in_style.Name)
heading_para.AppendText("Sales by Region")

document.SaveToFile("document_styles.docx", FileFormat.Docx)

Preview of the generated Word document.

Technical Explanation

• ParagraphStyle(document) creates a reusable style object associated with the current document
• ParagraphFormat controls layout-related settings such as alignment and text flow
• CharacterFormat defines font-level properties like size and boldness
• ApplyBaseStyle() allows the custom style to inherit semantic meaning and default behavior from a built-in Word style
• Adding the style to document.Styles makes it available for use across all sections

Built-in styles, such as Heading 2, can be added explicitly and applied in the same way, ensuring the document remains compatible with Word features like outlines and tables of contents.

4. Inserting Images into a Word Document

In Word’s document model, images are embedded objects that belong to paragraphs, which ensures they flow naturally with text. Paragraph-anchored images adjust pagination automatically and maintain relative positioning when content changes.

Adding an Image to a Paragraph

from spire.doc import Document, TextWrappingStyle, HorizontalAlignment, FileFormat

document = Document()
section = document.AddSection()
section.AddParagraph().AppendText("\r\n\r\nExample Image\r\n")

# Insert an image
image_para = section.AddParagraph()
image_para.Format.HorizontalAlignment = HorizontalAlignment.Center
image = image_para.AppendPicture("Screen.jpg")

# Set the text wrapping style
image.TextWrappingStyle = TextWrappingStyle.Square
# Set the image size
image.Width = 350
image.Height = 200
# Set the transparency
image.FillTransparency(0.7)
# Set the horizontal alignment
image.HorizontalAlignment = HorizontalAlignment.Center

document.SaveToFile("document_images.docx", FileFormat.Docx)

Preview of the generated Word document.

Technical details

• AppendPicture() inserts the image into the paragraph, making it part of the text flow
• TextWrappingStyle determines how surrounding text wraps around the image
• Width and Height control the displayed size of the image
• FillTransparency() sets the image opacity
• HorizontalAlignment can center the image within the paragraph

Adding images to paragraphs ensures they behave like part of the text flow.

• Pagination adjusts automatically when images change size.
• Surrounding text reflows correctly when content is edited.
• When exporting to formats like PDF, images maintain their relative position.

These behaviors are consistent with Word’s handling of inline images.

For more advanced image operations in Word documents using Python, see how to insert images into a Word document with Python for a complete guide.

5. Creating and Populating Tables

Tables are commonly used to present structured data such as reports, summaries, and comparisons.

Internally, a table consists of rows, cells, and paragraphs inside each cell.

Creating and Formatting a Table in a Word Document

from spire.doc import Document, DefaultTableStyle, FileFormat, AutoFitBehaviorType

document = Document()
section = document.AddSection()
section.AddParagraph().AppendText("\r\n\r\nExample Table\r\n")

# Define the table data
table_headers = ["Region", "Product", "Units Sold", "Unit Price ($)", "Total Revenue ($)"]
table_data = [
    ["North", "Laptop", 120, 950, 114000],
    ["North", "Smartphone", 300, 500, 150000],
    ["South", "Laptop", 80, 950, 76000],
    ["South", "Smartphone", 200, 500, 100000],
    ["East", "Laptop", 150, 950, 142500],
    ["East", "Smartphone", 250, 500, 125000],
    ["West", "Laptop", 100, 950, 95000],
    ["West", "Smartphone", 220, 500, 110000]
]

# Add a table to the section
table = section.AddTable()
table.ResetCells(len(table_data) + 1, len(table_headers))

# Populate table headers
for col_index, header in enumerate(table_headers):
    header_range = table.Rows[0].Cells[col_index].AddParagraph().AppendText(header)
    header_range.CharacterFormat.FontSize = 14
    header_range.CharacterFormat.Bold = True

# Populate table data
for row_index, row_data in enumerate(table_data):
    for col_index, cell_data in enumerate(row_data):
        data_range = table.Rows[row_index + 1].Cells[col_index].AddParagraph().AppendText(str(cell_data))
        data_range.CharacterFormat.FontSize = 12

# Apply a default table style and auto-fit columns
table.ApplyStyle(DefaultTableStyle.ColorfulListAccent6)
table.AutoFit(AutoFitBehaviorType.AutoFitToContents)

document.SaveToFile("document_tables.docx", FileFormat.Docx)

Preview of the generated Word document.

Technical details

• Section.AddTable() inserts the table into the section content flow
• ResetCells(rows, columns) defines the table grid explicitly
• Table[row, column] or Table.Rows[row].Cells[col] returns a TableCell

Tables in Word are designed so that each cell acts as an independent content container. Text is always inserted through paragraphs, and each cell can contain multiple paragraphs, images, or formatted text. This structure allows tables to scale from simple grids to complex report layouts, making them flexible for reports, summaries, or any structured content.

For more detailed examples and advanced operations using Python, such as dynamically generating tables, merging cells, or formatting individual cells, see how to insert tables into Word documents with Python for a complete guide.

6. Adding Headers and Footers

Headers and footers in Word are section-level elements. They are not part of the main content flow and do not affect body pagination.

Each section owns its own header and footer, which allows different parts of a document to display different repeated content.

Adding Headers and Footers in a Section

from spire.doc import Document, FileFormat, HorizontalAlignment, FieldType, BreakType

document = Document()
section = document.AddSection()
section.AddParagraph().AppendBreak(BreakType.PageBreak)

# Add a header
header = section.HeadersFooters.Header
header_para1 = header.AddParagraph()
header_para1.AppendText("Monthly Sales Report").CharacterFormat.FontSize = 12
header_para1.Format.HorizontalAlignment = HorizontalAlignment.Left

header_para2 = header.AddParagraph()
header_para2.AppendText("Company Name").CharacterFormat.FontSize = 12
header_para2.Format.HorizontalAlignment = HorizontalAlignment.Right

# Add a footer with page numbers
footer = section.HeadersFooters.Footer
footer_para = footer.AddParagraph()
footer_para.Format.HorizontalAlignment = HorizontalAlignment.Center
footer_para.AppendText("Page ").CharacterFormat.FontSize = 12
footer_para.AppendField("PageNum", FieldType.FieldPage).CharacterFormat.FontSize = 12
footer_para.AppendText(" of ").CharacterFormat.FontSize = 12
footer_para.AppendField("NumPages", FieldType.FieldNumPages).CharacterFormat.FontSize = 12

document.SaveToFile("document_header_footer.docx", FileFormat.Docx)
document.Dispose()

Preview of the generated Word document.

Technical notes

• section.HeadersFooters.Header / .Footer provides access to header/footer of the section
• AppendField() inserts dynamic fields like FieldPage or FieldNumPages to display dynamic content

Headers and footers are commonly used for report titles, company information, and page numbering. They update automatically as the document changes and are compatible with Word, PDF, and other export formats.

For more detailed examples and advanced operations, see how to insert headers and footers in Word documents with Python.

7. Controlling Page Layout with Sections

In Spire.Doc for Python, all page-level layout settings are managed through the Section object. Page size, orientation, and margins are defined by the section’s PageSetup and apply to all content within that section.

Configuring Page Size and Orientation

from spire.doc import PageSize, PageOrientation

section.PageSetup.PageSize = PageSize.A4()
section.PageSetup.Orientation = PageOrientation.Portrait

Technical explanation

• PageSetup is a layout configuration object owned by the Section
• PageSize defines the physical dimensions of the page
• Orientation controls whether pages are rendered in portrait or landscape mode

PageSetup defines the layout for the entire section. All paragraphs, tables, and images added to the section will follow these settings. Changing PageSetup in one section does not affect other sections in the document, allowing different sections to have different page layouts.

Setting Page Margins

section.PageSetup.Margins.Top = 50
section.PageSetup.Margins.Bottom = 50
section.PageSetup.Margins.Left = 60
section.PageSetup.Margins.Right = 60

Technical explanation

• Margins defines the printable content area for the section
• Margin values are measured in document units

Margins control the body content area for the section. They are evaluated at the section level, so you do not need to set them for individual paragraphs, and header/footer areas are not affected.

Using Multiple Sections for Different Layouts

When a document requires different page layouts, additional sections must be created.

landscape_section = document.AddSection()
landscape_section.PageSetup.Orientation = PageOrientation.Landscape

Technical notes

• AddSection() creates a new section and appends it to the document
• Each section maintains its own PageSetup, headers, and footers
• Content added after this call belongs to the new section

Using multiple sections allows mixing portrait and landscape pages or applying different layouts within a single Word document.

Below is an example preview of the above settings in a Word document:

8. Setting Document Properties and Metadata

In addition to visible content, Word documents expose metadata through built-in document properties. These properties are stored at the document level and do not affect layout or rendering.

Assigning Built-in Document Properties

document.BuiltinDocumentProperties.Title = "Monthly Sales Report"
document.BuiltinDocumentProperties.Author = "Data Analytics System"
document.BuiltinDocumentProperties.Company = "Example Corp"

Technical notes

• BuiltinDocumentProperties provides access to standard document properties
• Properties such as Title, Author, and Company can be set programmatically

Document properties are commonly used for file indexing, search, document management, and audit workflows. In addition to built-in properties, Word documents support other metadata such as Keywords, Subject, Comments, and Hyperlink base. You can also define custom properties using Document.CustomDocumentProperties.

For a guide on managing document custom properties with Python, see how to manage custom metadata in Word documents with Python.

9. Saving, Exporting, and Performance Considerations

After constructing a Word document in memory, the final step is saving or exporting it to the required output format. Spire.Doc for Python supports multiple export formats through a unified API, allowing the same document structure to be reused without additional formatting logic.

Saving and Exporting Word Documents in Multiple Formats

A document can be saved as DOCX for editing or exported to other commonly used formats for distribution.

from spire.doc import FileFormat

document.SaveToFile("output.docx", FileFormat.Docx)
document.SaveToFile("output.pdf", FileFormat.PDF)
document.SaveToFile("output.html", FileFormat.Html)
document.SaveToFile("output.rtf", FileFormat.Rtf)

The export process preserves document structure, including sections, tables, images, headers, and footers, ensuring consistent layout across formats. Check out all the supported formats in the FileFormat enumeration.

Performance Considerations for Document Generation

For scenarios involving frequent or large-scale Word document generation, performance can be improved by:

• Reusing document templates and styles
• Avoiding unnecessary section creation
• Writing documents to disk only after all content has been generated
• After saving or exporting, explicitly releasing resources using document.Close()

When generating many similar documents with different data, mail merge is more efficient than inserting content programmatically for each file. Spire.Doc for Python provides built-in mail merge support for batch document generation. For details, see how to generate Word documents in bulk using mail merge in Python.

Saving and exporting are integral parts of Word document generation in Python. By using Spire.Doc for Python’s export capabilities and following basic performance practices, Word documents can be generated efficiently and reliably for both individual files and batch workflows.

10. Common Pitfalls When Creating Word Documents in Python

The following issues frequently occur when generating Word documents programmatically.

Treating Word Documents as Plain Text

Issue Formatting breaks when content length changes.

Recommendation Always work with sections, paragraphs, and styles rather than inserting raw text.

Hard-Coding Formatting Logic

Issue Global layout changes require editing multiple code locations.

Recommendation Centralize formatting rules using styles and section-level configuration.

Ignoring Section Boundaries

Issue Margins or orientation changes unexpectedly affect the entire document.

Recommendation Use separate sections to isolate layout rules.

11. Conclusion

Creating Word documents in Python involves more than writing text to a file. A .docx document is a structured object composed of sections, paragraphs, styles, and embedded elements.

By using Spire.Doc for Python and aligning code with Word’s document model, you can generate editable, well-structured Word files that remain stable as content and layout requirements evolve. This approach is especially suitable for backend services, reporting pipelines, and document automation systems.

For scenarios involving large documents or document conversion requirements, a licensed version is required.

As modern front-end technologies evolve, more web applications are bringing Office document viewing and editing directly into the browser to improve performance, security, and user experience. React, one of the most popular front-end frameworks, is widely used to build document-centric applications.

In this article, you'll learn how to integrate Spire.OfficeJS into a React project to handle Word, Excel, PowerPoint, and PDF files efficiently on the client side.

Page Content:

• What Is Spire.OfficeJS
• Create a React Project and Integrate Spire.OfficeJS
• Implement File Upload and Editor Pages
• Run the project
• Demo Download
• FAQs

What Is Spire.OfficeJS

Spire.OfficeJS is a pure front-end document component suite developed by E-ICEBLUE, enabling the creation, viewing, and editing of Word, Excel, and PowerPoint documents, with built-in support for PDF viewing. Developers can complete the entire document workflow in the browser, from opening and editing to exporting, without installing Microsoft Office or relying on backend services.

Designed for performance and easy integration, Spire.OfficeJS fits a wide range of document-driven applications, from online platforms to education systems and admin dashboards.

Spire.OfficeJS product package includes the following components:

• Spire.WordJS
• Spire.ExcelJS
• Spire.PresentationJS
• Spire.PDFJS

Core Features:

• Multi-format support: Preview, edit, and export Word, Excel, and PowerPoint documents, with PDF preview support.
• Online editing: Edit Office documents directly in the browser, including text, tables, images, and styles.
• High-performance, pure front-end execution: Powered by WebAssembly, delivering lightweight loading and efficient performance with no backend involvement.
• Flexible integration: Easily integrates with React, Vue, Angular, and can also be used conveniently with vanilla JavaScript.

Create a React Project and Integrate Spire.OfficeJS

Step 1. Install Node.js

Download and install Node.js from the official website(https://nodejs.org/en/download/). After installation, open Command Prompt (cmd) and run the following command to verify the installed version:

node -v
npm -v

Step 2. Create a New React Project with Vite

Choose a project directory, open Command Prompt (cmd), and run the following command:

npm create vite@latest officejs-demo -- --template react

A new React project will be created and initialized.

Step 3. Install Dependencies Using npm

Open the "officejs-demo" project in VS Code, then run the following command to install "react-router-dom", which provides routing and navigation between pages:

npm install react-router-dom

Step 4. Integrate Spire.OfficeJS

Download the Spire.OfficeJS package. On Windows, double-click the run_genallfonts.bat file in the extracted package to run it. On Linux, use the command sh run_genallfonts.sh start to run the run_genallfonts.sh file in the extracted product package folder. After execution completes, a fontsweb folder will appear inside the web folder.

In your React project, create a new spire.officejs folder under the public directory, then copy the entire web folder (including fontsweb) into this directory. Ensure that the directory path matches the path referenced in Editor.jsx.

Implement File Upload and Editor Pages

1. App.jsx: Configure Routing and Global File State Management

Code:

import { createContext, useContext, useState } from 'react';
import { createBrowserRouter, RouterProvider } from 'react-router-dom';
import Home from './Home';
import Editor from './Editor';

//File state context
const FileContext = createContext();

export const useFileStore = () => useContext(FileContext);

function FileProvider({ children }) {
  const [file, setFile] = useState(null);
  const [fileUint8Data, setFileUint8Data] = useState(null);

  return (
    <FileContext.Provider value={{
      file,
      fileUint8Data,
      setFileData: setFile,
      setFileUint8Data
    }}>
      {children}
    </FileContext.Provider>
  );
}

const router = createBrowserRouter([
  { path: '/', element: <Home /> },
  { path: '/editor', element: <Editor /> },
]);

function App() {
  return (
    <FileProvider>
      <RouterProvider router={router} />
    </FileProvider>
  );
}

export default App;

2. Home.jsx: Set Up File Upload, File Handling, and Editor Navigation

Explanation:

• FileReader: To read local files from the user's device.
• Uint8Array: The binary data format required by OfficeJS WebAssembly for data input.
• useNavigate: A React Router hook for programmatic navigation between pages.
• Drag and Drop: Browser-based drag-and-drop support for file uploads.

Code:

import { useRef, useEffect } from "react"
import { useFileStore } from './App';
import { useNavigate } from 'react-router-dom';

function Home() {
    const { setFileData, setFileUint8Data } = useFileStore();
    const navigate = useNavigate();

    let dropArea = null;
    let fileInput = useRef();
    let file = null;
    let fileUint8Data = null;

    useEffect(() => {
        dropArea = document;

        //Prevent the default drag-and-drop behavior
        ['dragenter', 'dragover', 'dragleave', 'drop'].forEach(eventName => {
            dropArea.addEventListener(eventName, preventDefaults, false);
        });

        //Handle file drag-and-drop
        dropArea.addEventListener('drop', handleDrop, false);
    }, [])

    const preventDefaults = (e) => {
        e.preventDefault();
        e.stopPropagation();
    }

    const handleBtnClick = (e) => {
        e.preventDefault();
        fileInput.current.click();
    }

    const handleDrop = async (e) => {
        if (e.target && e.target.files)
            file = e.target.files[0]
        else if (e.dataTransfer && e.dataTransfer.files)
            file = e.dataTransfer.files[0];

        if (!file) return;

        fileUint8Data = await handleFile(file);
        setFileData(file);
        setFileUint8Data(fileUint8Data);
        openDocument();
    }

    const handleFile = (file) => {
        return new Promise((resolve, reject) => {
            const reader = new FileReader();
            reader.onload = () => {
                const arrayBuffer = reader.result;
                const uint8Array = new Uint8Array(arrayBuffer);
                resolve(uint8Array);
            };
            reader.onerror = (error) => reject(error);
            reader.readAsArrayBuffer(file);
        });
    }

    const openDocument = () => {
        navigate('/editor')
    }

    return (
        <div>
            <div>
                <h2>Upload Your File</h2>
                <div>
                    <p>Drag your file to the browser</p>
                     <p style={{ marginLeft: '20px' }}>or</p>
                    <button ref={fileInput} onClick={handleBtnClick}>Choose Your File</button>
                    <input
                        type="file"
                        id="fileInput"
                        ref={fileInput}
                        onChange={handleDrop}
                        style={{ display: 'none' }}
                    />
                </div>
            </div>
        </div>
    )
}

export default Home

3. Editor.jsx: Add and Integrate the OfficeJS Editor

Code:

import { useRef, useEffect } from "react"
import { useFileStore } from './App';
import { useNavigate } from 'react-router-dom';

function Editor() {
    const { file, fileUint8Data } = useFileStore();
    const navigate = useNavigate();

    const config = useRef({});
    let Editor = useRef(null);
    let Api = useRef(null);
    let originUrl = window.location.origin;

    useEffect(() => {
        if (!file) {
            navigate('/')
            return;
        }
        // Dynamically load Spire.OfficeJS
        loadScript();
    }, [])

    const loadScript = () => {
        var script = document.createElement('script');
        //Adjust according to your product package path
        script.setAttribute('src', '/spire.officejs/web/editors/spireapi/SpireCloudEditor.js');
        script.onload = () => initEditor()
        document.head.appendChild(script);
    }

    const initEditor = () => {
        let iframeId = 'iframeEditor';
        initConfig();
        Editor = new SpireCloudEditor.OpenApi(iframeId, config.value);
        window.Api = Api = Editor.GetOpenApi();
        OnWindowReSize();
    }

    const initConfig = () => {
        config.value = {
            "fileAttrs": {
                "fileInfo": {
                    "name": file.name,
                    "ext": getFileExtension(),
                    "primary": String(new Date().getTime()),
                    "creator": "User",
                    "createTime": new Date().toLocaleString()
                },
                "sourceUrl": originUrl + "/files/" + file.name,
                "createUrl": originUrl + "/open",
                "mergeFolderUrl": "",
                "fileChoiceUrl": "",
                "templates": {}
            },
            "user": {
                "id": "uid-1",
                "name": "User",
                "canSave": true,
            },
            "editorAttrs": {
                "editorMode": "edit",
                "editorWidth": "100%",
                "editorHeight": "100%",
                "editorType": "document",  // document/spreadsheet/presentation
                "platform": "desktop",
                "viewLanguage": "en",  // en/zh
                "isReadOnly": false,
                "canChat": true,
                "canComment": true,
                "canReview": true,
                "canDownload": true,
                "canEdit": true,
                "canForcesave": true,
                "embedded": {
                    "saveUrl": "",
                    "embedUrl": "",
                    "shareUrl": "",
                    "toolbarDocked": "top"
                },
                //Enable WebAssembly to improve performance
                "useWebAssemblyDoc": true,
                "useWebAssemblyExcel": true,
                "useWebAssemblyPpt": true,
                "spireDocJsLicense": "",
                "spireXlsJsLicense": "",
                "spirePresentationJsLicense": "",
                "spirePdfJsLicense": "",
                //Serverless mode: process files directly in memory without a backend
                "serverless": {
                    "useServerless": true,
                    "baseUrl": originUrl,
                    "fileData": fileUint8Data,  //The file's Uint8Array data
                },
                "events": {
                    "onSave": onFileSave
                },
                "plugins": {
                    "pluginsData": []
                }
            }
        };
    }

    const OnWindowReSize = () => {
        let wrapEl = document.getElementById("editor-container");
        if (wrapEl) {
            wrapEl.style.height = screen.availHeight + "px";
            window.scrollTo(0, -1);
            wrapEl.style.height = window.innerHeight + "px";
        }
    }

    const getFileExtension = () => {
        const filename = file.name.split(/[\\/]/).pop();
        return filename.substring(filename.lastIndexOf('.') + 1).toLowerCase() || '';
    }

    const onFileSave = (data) => {
        console.log('Saved data:', data)
        //Implement the save logic here
        //For example, send the file to a server or download it
    }

    return (
        <div id="editor-container">
            <div id="iframeEditor"></div>
        </div>
    )
}

export default Editor

4. main.jsx

Code:

import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import App from './App.jsx'

createRoot(document.getElementById('root')).render(
  //Note: React StrictMode causes the Spire  editor to render twice, so it's recommended to disable it
  <App />
)

5. vite.config.js - Customize the Development Server Port

Code:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  server: {
    host: '0.0.0.0',
    port: 5174
  },
  plugins: [react()],
})

Run the Project

Run the command npm run dev to start the configured project, then open your browser and visit http://localhost:5174/.

Upload a local document by dragging or clicking "Choose Your File" to open it for editing.

Go to "File > Download As" to download the document or convert it to other formats.

Demo Download

Click to download

FAQs:

1. Project creation error due to incompatible npm or Node.js versions:

This usually occurs when Node.js is outdated. Update to the latest version of Node.js to resolve the issue.

2. Dependency installation failure:

• Clear the npm cache.
• Delete node_modules and package-lock.json, then reinstall dependencies.
• Ensure you are in the correct project directory and do not run installation commands outside the Vite project.

3. Spire.OfficeJS files cannot be loaded:

• Verify that the web folder has been copied to the correct directory.
• Make sure the development server can access resources under the public directory at runtime.

Apply for License

To remove the evaluation message from generated documents or lift feature limitations, contact us to obtain a 30-day temporary license.