React-DOCX

Generate Microsoft Word documents (.docx) using React components and JSX.

Why React-DOCX?

Personally, I’ve always felt that when it comes to building documents, XML-style templating languages are the most natural fit. The docx library is excellent — it’s well-designed, feature-rich, and gives you full control over every aspect of a Word document.

However, working with it directly can feel a bit cumbersome at times, especially when managing deeply nested structures. That’s why I built React-DOCX — not to replace or reinvent docx, but to port it into a more expressive JSX syntax.

This project uses the same types, the same structure, and still depends on docx under the hood. The only difference is that you can now use React’s familiar patterns — components, hooks, and context — to build documents in a cleaner and more declarative way.

Design Philosophy

1. Direct Mapping - Props map directly to DOCX API, no abstraction layers
2. React Patterns - Full support for Context, hooks, and composition
3. TypeScript First - Complete type safety out of the box
4. Zero Config - No build configuration needed

Features

• Write DOCX with JSX - Use familiar React syntax to create Word documents
• Full TypeScript Support - Complete type safety with IntelliSense
• Direct DOCX API Mapping - Props map directly to the docx library API
• React Patterns - Supports Context, hooks, and component composition
• Zero Configuration - Just import and start creating documents

Installation

npm install @react-docx/core
# or
yarn add @react-docx/core
# or
pnpm add @react-docx/core

Quick Start

import React from "react";
import {
  Document,
  Section,
  Paragraph,
  TextRun,
  renderToBuffer,
} from "@react-docx/core";
import fs from "fs";

const MyDocument = () => (
  <Document>
    <Section>
      <Paragraph>
        <TextRun text="Hello World!" bold={true} size={28} />
      </Paragraph>
    </Section>
  </Document>
);

// Generate the document
const buffer = await renderToBuffer(<MyDocument />);
fs.writeFileSync("document.docx", buffer);

Core Concepts

Document Structure

Every document follows this hierarchy:

<Document>
  {/* Document-level properties and metadata */}
  <Section>
    {/* Section-level properties (margins, headers, footers) */}
    <Paragraph>
      {/* Paragraph-level properties (spacing, alignment) */}
      <TextRun /> {/* Text-level properties (font, size, color) */}
    </Paragraph>
  </Section>
</Document>

Document Component

The Document component accepts document-level properties including metadata and styles:

<Document
  title="My Resume"
  creator="John Doe"
  description="Professional resume"
>
  <Section>{/* content */}</Section>
</Document>

Section Component

Sections define page layout properties like margins, page size, headers, and footers:

<Section
  properties={{
    page: {
      margin: {
        top: 1440, // 1 inch (in twips: 1 inch = 1440 twips)
        right: 1440,
        bottom: 1440,
        left: 1440,
      },
    },
  }}
>
  {/* content */}
</Section>

Paragraph Component

Paragraphs contain text and inline elements:

<Paragraph
  spacing={{ before: 200, after: 200 }}
  alignment="center"
  indent={{ left: 720 }}
>
  <TextRun text="Centered paragraph" />
</Paragraph>

TextRun Component

TextRuns apply formatting to text:

<TextRun
  text="Hello World"
  bold={true}
  italics={true}
  size={24} // Font size in half-points (24 = 12pt)
  color="2B6CB0" // Hex color without #
  font="Arial"
/>

Advanced Features

Line Breaks

Use <Break /> to add line breaks within a paragraph:

<Paragraph>
  <TextRun text="First line" />
  <Break />
  <TextRun text="Second line" />
  <Break />
  <TextRun text="Third line" />
</Paragraph>

Tables

<Table
  width={{ size: 100, type: "pct" }}
  borders={{
    top: { style: "single", size: 6, color: "CCCCCC" },
    bottom: { style: "single", size: 6, color: "CCCCCC" },
  }}
>
  <TableRow>
    <TableCell>
      <Paragraph>
        <TextRun text="Cell 1" />
      </Paragraph>
    </TableCell>
    <TableCell>
      <Paragraph>
        <TextRun text="Cell 2" />
      </Paragraph>
    </TableCell>
  </TableRow>
</Table>

Hyperlinks

<ExternalHyperlink link="https://github.com">
  <TextRun text="Visit GitHub" color="0000FF" underline={{ type: "single" }} />
</ExternalHyperlink>

Page Breaks

<PageBreak />

API Reference

Components

• Document - Root document component
• Section - Document section with page layout
• Paragraph - Text paragraph
• TextRun - Formatted text
• Break - Line break within paragraph
• Table - Table element
• TableRow - Table row
• TableCell - Table cell
• ExternalHyperlink - External URL link
• InternalHyperlink - Internal bookmark link
• PageBreak - Page break
• Bookmark - Bookmark anchor
• Tab - Tab character
• ImageRun - Embedded image
• SymbolRun - Special symbol
• Math - Mathematical equation

Rendering Functions

• renderToBuffer(element) - Returns Promise<Buffer>
• renderToBlob(element) - Returns Promise<Blob>
• renderToBase64(element) - Returns Promise<string>

Type Safety

All components have full TypeScript support. Props map directly to the docx library interfaces, so you can reference docx documentation for detailed prop options.

import {
  DocumentProps,
  SectionProps,
  ParagraphProps,
  TextRunProps,
} from "@react-docx/core";

Examples

See the /examples directory for complete examples:

• basic.tsx - Basic document with text formatting
• advanced.tsx - Tables, hyperlinks, page breaks
• resume.tsx - Professional resume template

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

MIT © Silvi Lila

Acknowledgments

Built on top of the docx library by dolanmiu.