DOCX

Equations and Symbols

Math formulas with the Math API and ruby annotations for East Asian text

Math Formulas

The Math API lets you build mathematical equations using OOXML's Office Math Markup Language (OMML).

Basic Equation

import { Paragraph, Math: MathAPI, MathRun, MathFraction } from "@office-open/docx";

new Paragraph({
  children: [
    new MathAPI({
      children: [
        new MathFraction({
          numerator: "a",
          denominator: "b",
        }),
      ],
    }),
  ],
});

Complex Equation

import {
  Paragraph, Math: MathAPI, MathFraction, MathSubScript, MathSuperScript,
} from "@office-open/docx";

new Paragraph({
  children: [
    new MathAPI({
      children: [
        // x = (a + b) / c
        new MathRun("x"),
        new MathRun("="),
        new MathFraction({
          numerator: "a + b",
          denominator: "c",
        }),
      ],
    }),
  ],
});

Math Components

ComponentDescription
MathRoot equation container
MathRunText within an equation
MathFractionFraction (numerator/denominator)
MathSubScriptSubscript notation
MathSuperScriptSuperscript notation
MathRadicalSquare root and nth root
MathNarySummation, integrals, products
MathAccentAccents (hat, bar, tilde, etc.)
MathEqArrEquation array (aligned equations)
MathBorderBoxBorder box around expression
MathBoxBox with operator emulation
MathGroupChrGroup character (brace, bracket)
MathPhantPhantom (invisible placeholder)

MathBorderBox

Draw a border box around an expression with configurable borders and strikethroughs:

import { MathBorderBox } from "@office-open/docx";

new MathBorderBox({
    children: [new MathRun("a")],
});

// Hide top and bottom borders
new MathBorderBox({
    children: [new MathRun("b")],
    properties: {
        hideTop: true,
        hideBottom: true,
    },
});

BorderBox Properties

PropertyTypeDescription
hideTopbooleanHide top border
hideBottombooleanHide bottom border
hideLeftbooleanHide left border
hideRightbooleanHide right border
strikeHorizontalbooleanHorizontal strikethrough
strikeVerticalbooleanVertical strikethrough
strikeDiagonalUpbooleanBottom-left to top-right diagonal
strikeDiagonalDownbooleanTop-left to bottom-right diagonal

MathBox

Wrap content in a box, optionally emulating operator behavior:

import { MathBox } from "@office-open/docx";

new MathBox({
    children: [new MathRun("x + y")],
    properties: { opEmu: true },
});

MathGroupChr

Add a grouping character (brace, bracket, etc.) above or below content:

import { MathGroupChr } from "@office-open/docx";

new MathGroupChr({
    children: [
        new MathEqArr({
            rows: [[new MathRun("a")], [new MathRun("b")]],
        }),
    ],
    properties: {
        chr: "{", // Grouping character
        pos: "bot", // Position: "top" or "bot"
        vertJc: "top", // Vertical justification
    },
});

MathPhantom

Create invisible placeholders for spacing control:

import { MathPhant } from "@office-open/docx";

new MathPhant({
    children: [new MathRun("dy")],
    properties: {
        zeroAsc: true, // Zero ascent
        zeroDesc: true, // Zero descent
    },
});

Ruby Annotations

Ruby annotations provide pronunciation guides for East Asian text (furigana, pinyin, etc.):

import { Paragraph, createRuby } from "@office-open/docx";

new Paragraph({
    children: [
        createRuby({
            base: "漢字", // Base text
            text: "かんじ", // Ruby (phonetic) text
        }),
        createRuby({
            base: "汉字",
            text: "hànzì",
            language: "zh-CN", // Language identifier
        }),
    ],
});

Ruby Options

PropertyTypeDescription
basestringBase text to annotate
textstringRuby annotation text
alignment"left" | "center" | "right"Alignment (default: "center")
rubyFontSizenumberFont size in half-points
offsetnumberVertical offset in half-points
languagestringLanguage identifier (e.g., "ja-JP")
Copyright © 2026