Equations and Symbols

#Math Formulas

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

#Basic Equation

JSON

{
  "sections": [
    {
      "children": [
        {
          "paragraph": {
            "children": [
              {
                "math": {
                  "equations": [
                    ["x", " = ", { "fraction": { "numerator": ["a + b"], "denominator": ["c"] } }]
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

TypeScript

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

await generateDocument({
  sections: [
    {
      children: [
        {
          paragraph: {
            children: [
              {
                math: {
                  equations: [
                    ["x", " = ", { fraction: { numerator: ["a + b"], denominator: ["c"] } }],
                  ],
                },
              },
            ],
          },
        },
      ],
    },
  ],
});

#Complex Equation

JSON

{
  "sections": [
    {
      "children": [
        {
          "paragraph": {
            "children": [
              {
                "math": {
                  "equations": [
                    [
                      "x",
                      " = ",
                      {
                        "sum": {
                          "children": [
                            { "superScript": { "children": ["x"], "superScript": ["2"] } }
                          ],
                          "subScript": ["i=0"],
                          "superScript": ["n"]
                        }
                      }
                    ]
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

TypeScript

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

await generateDocument({
  sections: [
    {
      children: [
        {
          paragraph: {
            children: [
              {
                math: {
                  equations: [
                    [
                      "x",
                      " = ",
                      {
                        sum: {
                          children: [{ superScript: { children: ["x"], superScript: ["2"] } }],
                          subScript: ["i=0"],
                          superScript: ["n"],
                        },
                      },
                    ],
                  ],
                },
              },
            ],
          },
        },
      ],
    },
  ],
});

#Math Components

Component	Description
`math`	Root equation container
`fraction`	Fraction (numerator/denominator)
`subScript`	Subscript notation
`superScript`	Superscript notation
`subSuperScript`	Combined sub- and superscript
`radical`	Square root and nth root
`sum`	Summation (∑)
`integral`	Integral (∫)
`limitLower`	Lower limit notation
`limitUpper`	Upper limit notation
`function`	Named function (e.g. sin, cos)
`matrix`	Matrix (rows and columns)
`roundBrackets`	Parentheses grouping
`curlyBrackets`	Curly brace grouping
`accent`	Accents (hat, bar, tilde, etc.)
`bar`	Overline/underline bar
`eqArr`	Equation array (aligned equations)
`borderBox`	Border box around expression
`box`	Box with operator emulation
`groupChr`	Group character (brace, bracket)
`phant`	Phantom (invisible placeholder)

#Text in equations

Use a string for plain text or { text: "x" } for styled runs:

In the JSON API, use a string for plain text or { "text": "x" } for styled runs:

json

{ "math": { "children": ["x", " = ", { "text": "y" }] } }

#MathFraction

Numerator and denominator accept MathComponent[] arrays:

JSON:

json

{ "fraction": { "numerator": ["a + b"], "denominator": ["c"] } }

#MathRadical

JSON:

json

{ "radical": { "children": ["x + y"], "degree": ["3"] } }

#MathSubScript / MathSuperScript / MathSubSuperScript

JSON:

json

{ "subScript": { "children": ["x"], "subScript": ["i"] } }
{ "superScript": { "children": ["x"], "superScript": ["2"] } }
{ "subSuperScript": { "children": ["x"], "subScript": ["i"], "superScript": ["2"] } }

#MathSum / MathIntegral

JSON:

json

{ "sum": { "children": ["x"], "subScript": ["i=0"], "superScript": ["n"] } }
{ "integral": { "children": ["f(x)"], "subScript": ["a"], "superScript": ["b"] } }

#MathLimitLower / MathLimitUpper

JSON:

json

{ "limitLower": { "children": ["lim"], "limit": ["x→0"] } }

#MathFunction

JSON:

json

{ "function": { "name": ["sin"], "children": ["x"] } }

#MathMatrix

JSON:

json

{
  "matrix": {
    "rows": [
      ["a", "b"],
      ["c", "d"]
    ]
  }
}

#Brackets

All bracket types produce m:d delimiter elements with different characters:

JSON:

json

{ "roundBrackets": ["x + y"] }
{ "squareBrackets": ["x"] }
{ "curlyBrackets": ["a", "b"] }
{ "angledBrackets": ["x"] }

#Math Accent

Accents (hat, tilde, etc.):

JSON:

json

{ "accent": { "children": ["x"], "accentCharacter": "^" } }

#Math Bar

Overline/underline bars:

JSON:

json

{ "bar": { "children": ["x"], "type": "top" } }

#MathEqArr

Equation array for aligned equations:

JSON:

json

{
  "eqArr": {
    "rows": [
      ["a", "=", "b + c"],
      ["d", "=", "e + f"]
    ]
  }
}

#MathBorderBox

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

JSON:

json

{ "borderBox": { "children": ["a"] } }

Hide the top and bottom borders:

json

{ "borderBox": { "children": ["b"], "properties": { "hideTop": true, "hideBottom": true } } }

BorderBox Properties

Property	Type	Description
`hideTop`	`boolean`	Hide top border
`hideBottom`	`boolean`	Hide bottom border
`hideLeft`	`boolean`	Hide left border
`hideRight`	`boolean`	Hide right border
`strikeHorizontal`	`boolean`	Horizontal strikethrough
`strikeVertical`	`boolean`	Vertical strikethrough
`strikeDiagonalUp`	`boolean`	Bottom-left to top-right diagonal
`strikeDiagonalDown`	`boolean`	Top-left to bottom-right diagonal

#MathBox

Wrap content in a box, optionally emulating operator behavior:

JSON:

json

{ "box": { "children": ["x + y"] } }

#MathGroupChr

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

JSON:

json

{ "groupChr": { "children": ["a", "b"] } }

#MathPhantom

Create invisible placeholders for spacing control:

JSON:

json

{ "phant": { "children": ["dy"] } }

#Advanced Math Properties

Beyond the basic components above, several math elements support a properties block for fine-grained control.

#Delimiter Properties

Bracket types (roundBrackets, squareBrackets, curlyBrackets, angledBrackets) accept an object form with children and properties to customize characters, separators, and growth:

{
  roundBrackets: {
    children: [{ text: "a, b, c" }],
    properties: {
      beginCharacter: "(",
      endCharacter: ")",
      separatorCharacter: ",",
      grow: true,
      shape: "centered", // "centered" | "match"
    },
  },
}

Property	Type	Description
`beginCharacter`	`string`	Opening character
`endCharacter`	`string`	Closing character
`separatorCharacter`	`string`	Element separator
`grow`	`boolean`	Grow with content height
`shape`	`"centered" \| "match"`	Delimiter shape

#N-ary Properties (sum / integral)

Control where sub/super limits sit and whether the operator grows:

json

{
  "sum": {
    "children": [
      {
        "text": "x"
      }
    ],
    "subScript": [
      {
        "text": "i=0"
      }
    ],
    "superScript": [
      {
        "text": "n"
      }
    ],
    "properties": {
      "limitLocation": "undOvr",
      "grow": true
    }
  }
}

Property	Type	Description
`limitLocation`	`"subSup" \| "undOvr"`	Limit position relative to operator
`grow`	`boolean`	Operator grows with content

#Fraction Argument Size

Scale the numerator/denominator font independently:

json

{
  "fraction": {
    "numerator": [
      {
        "text": "1"
      }
    ],
    "denominator": [
      {
        "text": "2"
      }
    ],
    "numeratorArgumentSize": 80,
    "denominatorArgumentSize": 80
  }
}

#Sub/Super Script Alignment

{
  subSuperScript: {
    children: [{ text: "x" }],
    subScript: [{ text: "i" }],
    superScript: [{ text: "2" }],
    alignScript: true,
  },
}

#Symbol Runs

Insert Wingdings or other symbol font characters inline:

JSON

{
  "sections": [
    {
      "children": [
        {
          "paragraph": {
            "children": [
              "Arrow: ",
              { "symbolRun": { "char": "F021", "symbolFont": "Wingdings" } },
              " check: ",
              { "symbolRun": { "char": "F052", "symbolFont": "Wingdings" } }
            ]
          }
        }
      ]
    }
  ]
}

TypeScript

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

await generateDocument({
  sections: [
    {
      children: [
        {
          paragraph: {
            children: [
              "Arrow: ",
              { symbolRun: { char: "F021", symbolFont: "Wingdings" } },
              " check: ",
              { symbolRun: { char: "F052", symbolFont: "Wingdings" } },
            ],
          },
        },
      ],
    },
  ],
});

#SymbolRun Options

Option	Type	Description
`char`	`string`	Hex character code (e.g. `"F021"`)
`symbolFont`	`string`	Font name (default: `"Wingdings"`)
`bold`	`boolean`	Bold
`italic`	`boolean`	Italic
`color`	`string`	Hex color code
`size`	`number`	Font size in points

#Ruby Annotations

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

json

{
  "paragraph": {
    "children": [
      {
        "ruby": {
          "properties": {
            "alignment": "center",
            "fontSize": 10,
            "raise": 4,
            "baseFontSize": 18,
            "languageId": "ja-JP"
          },
          "base": { "children": ["漢字"] },
          "text": { "children": ["かんじ"] }
        }
      },
      {
        "ruby": {
          "properties": {
            "alignment": "center",
            "fontSize": 10,
            "raise": 4,
            "baseFontSize": 18,
            "languageId": "zh-CN"
          },
          "base": { "children": ["汉字"] },
          "text": { "children": ["hànzì"] }
        }
      }
    ]
  }
}

#Ruby Options

Ruby is an inner child of a run. Its properties, text, and base fields mirror the required w:rubyPr, w:rt, and w:rubyBase elements. Both content fields accept formatted runs.

Property	Type	Description
`properties`	`RubyPropertiesOptions`	Required ruby layout properties
`base`	`RubyContentOptions`	Formatted base-text runs
`text`	`RubyContentOptions`	Formatted annotation-text runs

RubyPropertiesOptions requires alignment, fontSize, raise, baseFontSize, and languageId; dirty is optional.