docx-jsx v0.0.3

docx-jsx

docx is nice. JSX is nice. Both together is really nice.

What is this?

docx is a great package for creating .docx files, but the API it exposes for building the documents is a little awkward, particularly when you're used to putting hierarchical elements together with XML-like syntax.

This package allows you to write:

/** @jsx createElement */
import { createElement, Document, Paragraph, Section, TextRun } from "docx-jsx";

const createDocument = () => (
  <Document>
    <Section>
      <Paragraph>
        <TextRun>Hello World</TextRun>
        <TextRun bold={true}>Foo Bar</TextRun>
        <TextRun bold={true} text={"\tGithub is the best"}></TextRun>
      </Paragraph>
    </Section>
  </Document>
);

Instead of the original example:

import { Document, Paragraph, TextRun } from "docx";

const createDocument = () => {
  // Create document
  const doc = new Document();

  // Documents contain sections, you can have multiple sections per document, go here to learn more about sections
  // This simple example will only contain one section
  doc.addSection({
    properties: {},
    children: [
      new Paragraph({
        children: [
          new TextRun("Hello World"),
          new TextRun({
            text: "Foo Bar",
            bold: true
          }),
          new TextRun({
            text: "\tGithub is the best",
            bold: true
          })
        ]
      })
    ]
  });

  return doc;
};

How do I use it?

Install docx-jsx and docx (which is a peer dependency):

npm install docx@5 docx-jsx

The example above uses /** @jsx createElement */ to get the Babel JSX plugin to use docx-jsx's createElement instead of the default React.createElement. If you are using some other method to process JSX, consult the appropriate documentation.

You can import most of the docx elements, like Document and TextRun, from either docx or docx-jsx. However note that:

• Section does not exist in the docx package; and
• TabStop does exist, but is overridden in this package for functionality reasons;

so you must import them from docx-jsx for correct behaviour.

API improvements

In general, you can translate the docx API directly to JSX. However, to make the element structure a bit neater, the following elements can be passed as children:

• Sections can be children of a Document, rather than calling addSection

• TableRow elements can be children of a Table, rather than passing them as the rows property

• Header and Footer elements can be children of a Section, rather than setting the default in the headers or footers prop

• TabStops can be children of a Paragraph, rather than using the tabStops prop directly

Gotchas

Some special characters don't seem to be handled very well by JSX. If you need e.g. a tab character in a TextRun (see example above), use the text prop expression form, rather than the string literal form or passing the text as a child of the element:

<TextRun>\tDon't do this</TextRun>
<TextRun text="\tor this" />
<TextRun text={'\tdo this instead'} />

ESLint

You will need to disable the rule react/style-prop-object for files including docx JSX, where the style prop is a string. You can do this by adding /* eslint-disable react/style-prop-object */ to the top of each file, for example.

How's it going?

This is still in pre-release phase, I'm working through the examples in the docs one by one...

• Get initial example working
• Document properties examples
• tabStops example
• Work through demos
  • 1. Basic
  • 2. Declarative styles
  • 3. Numbering and bullet points
  • 4. Basic table
  • 6. Page borders
  • 7. Landscape
  • 8. Header & footer
  • 14. Page numbers
• Handle fragments