Convenience functions

OOXML and this library mainly uses a unit called twentieths of a point or twip for short. a twip is a typographical measurement, defined as 1/20 of a typographical point. One twip is 1/1440 inch, or 17.64 μm. This unit is not intuitive for many users, so some functions were created to help

More info here: https://en.wikipedia.org/wiki/Twip

Convert Inches to Twip

import { convertInchesToTwip } from "betterdocx";

const twip = convertInchesToTwip(1); // returns 1440
const twip = convertInchesToTwip(0.5); // returns 720

Convert Millimeters to Twip

import { convertMillimetersToTwip } from "betterdocx";

const twip = convertMillimetersToTwip(50); // returns 2834

Measurement strings

Many size-related options across the API accept a measurement string instead of a raw twip number, so you can skip the conversion entirely. Two string types are used:

• UniversalMeasure / PositiveUniversalMeasure: a number followed by a unit — mm, cm, in, pt, pc or pi. For example "8.5in", "12pt", "2cm". The positive variant disallows negative values.
• Percentage: a number followed by %, e.g. "50%".

Universal measures are accepted wherever the option type allows them alongside a number — for example page sizes and margins, paragraph indents and spacing, and font sizes. Table and column widths additionally accept a Percentage:

new Document({
    sections: [
        {
            properties: {
                page: {
                    size: { width: "8.5in", height: "11in" },
                    margin: { top: "2cm", bottom: "2cm" },
                },
            },
            children: [
                new Paragraph({
                    indent: { left: "0.5in" },
                    children: [new TextRun({ text: "Hello", size: "12pt" })],
                }),
                new Table({
                    width: { size: "50%", type: WidthType.PERCENTAGE },
                    rows: [/* ... */],
                }),
            ],
        },
    ],
});

When a plain number is passed to these options instead, it is interpreted in the option's native unit (usually twips, or half-points for font sizes).

Unique ID generators

These helpers are exported mainly for building custom low-level components (they are what the library uses internally); most users won't need them.

import { uniqueId, hashedId, uniqueNumericIdCreator } from "betterdocx";

const id = uniqueId(); // e.g. "6fa459ea-ee8a-4ca4-894e-db77e160355e"
const hash = hashedId("some content"); // e.g. "aabbccdd-12" (stable for the same input)

const nextId = uniqueNumericIdCreator();
nextId(); // 1
nextId(); // 2