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. In your React project, create a new spire.officejs folder under the public directory, then copy the web folder from the extracted package into it. 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.

Spire.OfficeJS is a WebAssembly-based Office document editor that enables users to open, view, and edit Word, Excel, and PowerPoint documents directly in the browser. In this tutorial, we will walk through how to integrate Spire.OfficeJS into a Vue 3 application (Vue 3 + Vite), and build a fully client-side web application that supports online Office document editing—without relying on server-side document conversion.

By the end of this guide, you will have a runnable Vue project that allows users to upload Office documents and edit them directly in the browser using Spire.OfficeJS.

On this page:

• What Is Spire.OfficeJS
• How Spire.OfficeJS Works
• Preparation
• Integrating Spire.OfficeJS
• FAQs
• Conclusion
• Sample Project Download

What Is Spire.OfficeJS

Spire.OfficeJS is a web-based online Office document editing component that consists of four modules: Spire.WordJS, Spire.ExcelJS, Spire.PresentationJS, and Spire.PDFJS. It provides viewing and real-time editing capabilities for documents such as Word files, Excel spreadsheets, and PowerPoint presentations.

Spire.OfficeJS runs directly in the browser and can be deployed in any web project without installing plugins or relying on client-side software.

Key Features

• Pure front-end rendering: Based on WebAssembly, allowing document editing without server-side conversion.
• Rich editing capabilities: Supports document editing, comments, annotations, review, and saving.
• Multi-format support: DOC, DOCX, XLS, XLSX, PPT, PPTX, PDF (view), and more.
• High integrability: Can be flexibly embedded into Vue, React, Angular, or pure HTML projects.
• High customizability: Supports toolbar configuration, user permissions, save callbacks, plugin extensions, and more.

Spire.OfficeJS is suitable for enterprise systems, document management systems (DMS), collaboration platforms, online learning systems, and form-based applications.

How Spire.OfficeJS Works

Spire.OfficeJS is built on WebAssembly-based Office rendering engines that execute directly in the browser. The simplified workflow is:

1. A user uploads an Office document via the browser.
2. The file is read as binary data (Uint8Array).
3. The binary data is passed directly to the WebAssembly runtime.
4. The document is parsed, rendered, and edited client-side.
5. Save actions trigger callbacks for custom persistence logic.

Unlike traditional server-based Office editors, no server-side document conversion or rendering is required, significantly reducing infrastructure complexity and latency.

Preparation

Install Node.js

Download and install Node.js 22.12.0 or later from the official Node.js website. Node.js 22+ is recommended to ensure compatibility with Vite, modern ES module tooling, and WebAssembly-related workflows.

Verify the installation:

node -v
npm -v

Create a Vue 3 Project

Step 1: Create a project folder

Create a new folder to store the project files.

Step 2: Enter the folder via Command Line

cd /d d:\demo

Step 3: Initialize a Vue 3 project

npm init vue@latest

Rename the project to vue-spire and skip optional features to create a minimal Vue 3 project.

Step 4: Start the development server

cd vue-spire
npm run dev

Integrating Spire.OfficeJS

Step 1: Download the product package

Download Spire.OfficeJS product package from our website. After extracting the package, you will find a web folder containing the editor’s static assets and WebAssembly files.

Step 2: Copy static resources to the Public directory

In your Vue project:

• Open the project in VS Code.
• Create a folder: public/spire.cloud .
• Copy the entire web folder into it. This allows the editor resources to be accessed via /spire.cloud/web/....

Step 3: Install required dependencies

Install Pinia and Vue Router manually to keep the project setup explicit and easy to follow.

npm install pinia
npm install vue-router@4

Step 4: Create the project structure

Create the following structure under src :

src/
├── router/
│   ├── index.js
├── stores/
│   ├── file.js
├── views/
│   ├── FileUpload.vue
│   └── Spire.OfficeJS.vue

Step 5: Setup application

1. main.js — Application initialization

This file initializes the Vue application and registers Pinia and Vue Router. Pinia is used to manage shared document data, while Vue Router controls page navigation between the file upload view and the document editor view.

import { createApp } from 'vue'
// Import Pinia
import { createPinia } from 'pinia'
import App from './App.vue'
import router from './router'

const app = createApp(App)

// Create Pinia instance
const pinia = createPinia()

// Register Pinia and Router to the Vue application
app.use(pinia)
app.use(router)
app.mount('#app')

2. App.vue — Root component

App.vue serves as the root container of the application. It renders different pages dynamically using RouterView, allowing the file upload page and the document editor to be loaded as separate routes without reloading the application.

<script setup>
import { RouterView } from 'vue-router'
</script>

<template>
    <RouterView/>
</template>

3. Router index.js — Page navigation

The router defines the navigation flow of the application. The root route (/) is used for file upload, while /document loads the Spire.OfficeJS editor. This separation allows users to upload a document first and then open it in the editor with shared state preserved.

import { createRouter, createWebHistory } from 'vue-router'
import FileUpload from '../views/FileUpload.vue'
import SpireOfficeJs from '../views/Spire.OfficeJS.vue'

const router = createRouter({
    history: createWebHistory(),
    routes: [
        {
            path: '/',
            name: 'upload',
            component: FileUpload
        },
        {
            path: '/document',
            name: 'document',
            component: SpireOfficeJs
        },
        {
            path: '/:pathMatch(.*)*',
            redirect: '/'
        }
    ]
})

4. Pinia Store (file.js) — File state management

The Pinia store is responsible for sharing file metadata and binary data between different views. The uploaded file is converted into a Uint8Array and stored here so that it can be passed directly to Spire.OfficeJS in serverless mode.

import { ref } from 'vue'
// Import defineStore from Pinia to define a state management store
import { defineStore } from 'pinia'

// Define a file state management store
export const useFileStore = defineStore('file', () => {
  // Store the uploaded file object (File type)
  let file = ref(null)
  // Store the file binary data (Uint8Array format) for editor loading
  let fileUint8Data = ref(null);

  // Set the file object
  function setFileData(data) {
    file.value = data;
  }
  // Set the file binary data
  function setFileUint8Data(data) {
    fileUint8Data.value = data;
  }
  // Export state and methods for component usage
  return { file, fileUint8Data, setFileData, setFileUint8Data }
})

5. FileUpload.vue — File upload page

FileUpload.vue is responsible for handling user-selected Office documents before they are passed to the editor. It reads the uploaded file using the browser File API and converts it into a Uint8Array, which is required by Spire.OfficeJS in serverless mode.

<template>
    <main>
        <button @click="btnClick">Choose Your File</button>
        <label>
            <input id="input" type="file" @change="handleFileChange" style="display: none;" />
        </label>
    </main>
</template>

<script setup>
import { useRouter } from 'vue-router'
import { useFileStore } from '../stores/file'

// Router instance: redirect to /document after successful upload
const router = useRouter()
// Pinia Store: store the user-uploaded file and binary data
const fileStore = useFileStore()

// Handle file upload
async function handleFileChange(event) {
    // Get the file selected by the user through the input change event
    const selectedFile = event.target.files?.[0]
    if (!selectedFile) {
        return
    }

    // Save the original File object and binary data for the editor to read
    fileStore.setFileData(selectedFile)
    const buffer = await selectedFile.arrayBuffer()
    fileStore.setFileUint8Data(new Uint8Array(buffer))

    // Redirect to the document editing page after successful upload
    router.push('/document')
}
function btnClick() {
    var btn = document.querySelector('#input');
    btn.click()
}
</script>

6. Spire.OfficeJs.vue — Online editor integration

Spire.OfficeJs.vue is the core integration component where the Spire.OfficeJS editor is initialized and rendered. It dynamically loads the Spire.OfficeJS runtime, configures editor behavior, and passes the document binary data to the WebAssembly engine using serverless mode.

<template>
    <div class="form">
        <div id="iframeEditor">
        </div>
    </div>
</template>

<script setup>
import { ref, onMounted, onUnmounted } from 'vue';
import { storeToRefs } from 'pinia';
import { useFileStore } from '../stores/file.js'
import { useRouter } from 'vue-router';

const fileStore = useFileStore()
// Data stored in Pinia
const { file, fileUint8Data } = storeToRefs(fileStore)
const router = useRouter()
const config = ref({});
const isOpened = ref(false);
const editorInstance = ref(null);
const apiInstance = ref(null);
const originUrl = window.location.origin

onMounted(() => {
    // Redirect back to upload page if no file exists
    if (!file.value) {
        router.replace('/');
        return;
    }
    // Load editor script dynamically
    loadScript();
    window.addEventListener('resize', OnWindowReSize);
})

onUnmounted(() => {
    window.removeEventListener('resize', OnWindowReSize);
})

// Initialize the configuration object required by the editor
function initConfig() {
    if (!file.value) {
        throw new Error('File not found, please upload again');
    }

    if (!fileUint8Data.value) {
        throw new Error('File data not found, please upload again');
    }

    config.value = {
        "fileAttrs": {
            "fileInfo": {
                "name": file.value.name,
                "ext": getFileExtension(),
                "primary": String(new Date().getTime()),
                "creator": "Jonn",
                "createTime": "2022-04-18 11:30:43"
            },
            "sourceUrl": originUrl + "/files/__ffff_192.168.2.134/" + file.value.name,
            "createUrl": originUrl + "/open",
            "mergeFolderUrl": "",
            "fileChoiceUrl": "",
            "templates": {}

        },
        "user": {
            "id": "uid-1",
            "name": "Jonn",
            "canSave": true,
        },
        "editorAttrs": {
            "editorMode": "edit",
            "editorWidth": "100%",
            "editorHeight": "100%",
            "editorType": "document",
            "platform": "desktop", // desktop / mobile / embedded
            "viewLanguage": "en", // en / zh
            "isReadOnly": false,
            "canChat": true,
            "canComment": true,
            "canReview": true,
            "canDownload": true,
            "canEdit": true,
            "canForcesave": true,
            "embedded": {
                "saveUrl": "",
                "embedUrl": "",
                "shareUrl": "",
                "toolbarDocked": "top"
            },
            "useWebAssemblyDoc": true,
            "useWebAssemblyExcel": true,
            "useWebAssemblyPpt": true,
            "spireDocJsLicense": "",
            "spireXlsJsLicense": "",
            "spirePresentationJsLicense": "",
            "spirePdfJsLicense": "",
            "serverless": {
                "useServerless": true,
                "baseUrl": originUrl,
                "fileData": fileUint8Data.value,
            },
            "events": {
                "onSave": onFileSave
            },
            "plugins": {
                "pluginsData": []
            }
        }
    };
}

// Create and render the SpireCloudEditor instance
function initEditor() {
    let iframeId = 'iframeEditor';

    initConfig();
    isOpened.value = true;
    editorInstance.value = new SpireCloudEditor.OpenApi(iframeId, config.value); // Create editor instance
    window.Api = apiInstance.value = editorInstance.value.GetOpenApi(); // Expose OpenApi for debugging/saving
    OnWindowReSize();
}

// Get the uploaded file extension for fileInfo.ext
function getFileExtension() {
    const filename = file.value.name.split(/[\\/]/).pop();
    // Get the substring after the last dot
    return filename.substring(filename.lastIndexOf('.') + 1).toLowerCase() || '';
}

// Adjust editor container size to fit the window
function OnWindowReSize() {
    let wrapEl = document.getElementsByClassName("form");
    if (wrapEl.length) {
        wrapEl[0].style.height = screen.availHeight + "px";
        window.scrollTo(0, -1);
        wrapEl[0].style.height = window.innerHeight + "px";
    }
}

// Dynamically load the SpireCloudEditor script to avoid duplicate injection
function loadScript() {
    if (window.SpireCloudEditor) {
        initEditor()
        return
    }
    const script = document.createElement('script');
    script.setAttribute('src', '/spire.cloud/web/editors/spireapi/SpireCloudEditor.js');
    script.onload = () => initEditor()
    document.head.appendChild(script);
}

// Save callback for the Spire editor, can be connected to custom save logic
function onFileSave(data) {
    console.log('save data', data)
}

</script>

<style>
.form,
iframe,
body {
    min-height: 100vh !important;
    min-width: 100vh !important;
}
</style>

Step 6: Run the project

Start the development server:

npm run dev

Open the browser and navigate to: http://localhost:5173/

Upload a document and start editing it directly in the browser.

FAQs

Q1. Why does the editor load a blank page?

This usually occurs when static resource paths are incorrect or required WebAssembly files are missing. Ensure the web directory is correctly placed under public/spire.cloud and that SpireCloudEditor.js is accessible.

Q2. Why doesn’t the document open after uploading?

The editor requires the file to be passed as a Uint8Array. Verify that the file data is correctly read, stored in Pinia, and assigned to serverless.fileData.

Q3. Can Spire.OfficeJS run without a backend server?

Yes. When serverless.useServerless is enabled, all document loading, rendering, and editing are performed entirely in the browser using WebAssembly.

Q4. Which file formats are supported by Spire.OfficeJS?

Spire.OfficeJS supports Word (.doc, .docx), Excel (.xls, .xlsx), PowerPoint (.ppt, .pptx), and PDF (.pdf) files.

Q5. How can I save the edited document?

Use the onSave event to capture the edited document data and implement custom logic to upload, store, or download the file.

Conclusion

By following this tutorial, you have successfully integrated Spire.OfficeJS into a Vue 3 application and built a fully client-side Office document editor powered by WebAssembly. This approach eliminates server-side document conversion while providing a rich, responsive editing experience directly in the browser.

Demo Download

Click to download