Formatting

A DOCX file can be painted in all your favorite colors in a few ways;

• Using the formatting props of individual components
• Referencing components to a custom style that is saved in DOCX

Formatting props

The <Paragraph>, <Text>, <Section> and <Table> components each accept a bunch of props specific to the purpose of those components. Most of the time those props deal with formatting directly. Often, the props of a component are then an alias for the formatting properties type, with which you could specify fonts, spaces, etc. Not all of MS Word's formatting options are already implemented -- if you need something please feel invited to open an issue or even a pull-request.

Please refer to the API documentation for the full list of currently supported formatting options;

• ParagraphProperties, controls the paragraph and pilcrow symbol of it, when it is made visible in Word
• TextProperties, controls styling of the (paragraph) text.
• SectionProperties, controls the styling of sections and page size/orientation.
• TableProperties, controls the styling of tables.

For example:

<Paragraph indentation={{ left: cm(1) }}>
    This paragraph is indented by 1 centimeter on the left.
</Paragraph>

<Paragraph>
    <Text isItalic isBold isUnderline="wave">This text is formatted like a train wreck.</Text>
</Paragraph>

<Section pageWidth={cm(30)} pageHeight={cm(10)}>
    <Paragraph indentation={{ left: cm(1) }}>
        This paragraph is indented by 1 centimeter on the left.
    </Paragraph>
</Section>

Custom styles

You may prefer to define custom styles instead. Styles accept the same formatting properties as the components themselves:

const doc = Docx.fromNothing();

const style = doc.styles.add({
    type: 'paragraph',
    paragraph: {
        alignment: 'center',
    },
});

doc.document.set(
    <Paragraph style={style} />
);

The styles object is a union discriminating on the type property. The folling shapes are accepted:

{
    type: 'paragraph';
    basedOn?: string;
    // The paragraph and pilcrow symbol:
    paragraph?: ParagraphProperties & TextProperties;
    // Text inside the paragraph:
    text?: TextProperties;
}

{
    type: 'character';
    basedOn?: string;
    text?: TextProperties;
}

{
    type: 'table';
    basedOn?: string;
    table?: TableProperties;
}

Styles work very well with XML rendering, since often certain elements or attributes map directly to one of your custom styles.

Lengths

The OOXML standard uses a confusing selection of units of lengths; points, half points, eight points, twentieths-of-points, and English metric units. You may also want to use centimeters or inches.

To make things easier, just about every docxml API that is concerned with a size accepts an object of type UniversalSize. All you have to do is use the functions provided for entering a size in the unit of your preference:

• cm(amount: number): UniversalSize
  Converts centimeters to any of the other units of length.
• emu(amount: number): UniversalSize
  Converts English metric units to any of the other units of length.
• hpt(amount: number): UniversalSize
  Converts half-points to any of the other units of length.
• inch(amount: number): UniversalSize
  Converts inches to any of the other units of length.
• pt(amount: number): UniversalSize
  Converts points to any of the other units of length.
• twip(amount: number): UniversalSize
  Converts twentieth-points to any of the other units of length.

Any of these functions returns a UniversalSize object which contains the information for downstream to use the unit expected for that particular bit of OOXML;

const one_inch = inch(1);
// one_inch = { pt: 72, emu: 914400, hpt: 144, opt: 576, twip: 1440, inch: 1, cm: 2.54 }

For example:

<Paragraph indent={{ left: cm(1) }} />