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
{
"sections": [
{
"children": [
{
"paragraph": {
"children": [
{
"math": {
"children": [
"x",
" = ",
{ "fraction": { "numerator": ["a + b"], "denominator": ["c"] } }
]
}
}
]
}
}
]
}
]
}
import { generateDocument } from "@office-open/docx";
await generateDocument({
sections: [
{
children: [
{
paragraph: {
children: [
{
math: {
children: [
"x",
" = ",
{ fraction: { numerator: ["a + b"], denominator: ["c"] } },
],
},
},
],
},
},
],
},
],
});
Complex Equation
{
"sections": [
{
"children": [
{
"paragraph": {
"children": [
{
"math": {
"children": [
"x",
" = ",
{
"sum": {
"children": [
{ "superScript": { "children": ["x"], "superScript": ["2"] } }
],
"subScript": ["i=0"],
"superScript": ["n"]
}
}
]
}
}
]
}
}
]
}
]
}
import { generateDocument } from "@office-open/docx";
await generateDocument({
sections: [
{
children: [
{
paragraph: {
children: [
{
math: {
children: [
"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:
import { generateDocument } from "@office-open/docx";
await generateDocument({
sections: [
{
children: [
{
paragraph: {
children: [
{
math: {
children: ["x", " = ", { text: "y" }],
},
},
],
},
},
],
},
],
});
In the JSON API, use a string for plain text or { "text": "x" } for styled runs:
{ "math": { "children": ["x", " = ", { "text": "y" }] } }
MathFraction
Numerator and denominator accept MathComponent[] arrays:
import { generateDocument } from "@office-open/docx";
await generateDocument({
sections: [
{
children: [
{
paragraph: {
children: [
{
math: {
children: [
{
fraction: {
numerator: ["a"],
denominator: ["b"],
fractionType: "bar", // "bar" (default) | "skw" | "lin" | "noBar"
},
},
],
},
},
],
},
},
],
},
],
});
JSON:
{ "fraction": { "numerator": ["a + b"], "denominator": ["c"] } }
MathRadical
import { generateDocument } from "@office-open/docx";
await generateDocument({
sections: [
{
children: [
{
paragraph: {
children: [
{
math: {
children: [
{
radical: {
children: ["x + y"], // Radicand
degree: ["3"], // Optional: nth root degree
},
},
],
},
},
],
},
},
],
},
],
});
JSON:
{ "radical": { "children": ["x + y"], "degree": ["3"] } }
MathSubScript / MathSuperScript / MathSubSuperScript
import { generateDocument } from "@office-open/docx";
await generateDocument({
sections: [
{
children: [
{
paragraph: {
children: [
{
math: {
children: [
{ subScript: { children: ["x"], subScript: ["i"] } },
{ superScript: { children: ["x"], superScript: ["2"] } },
{ subSuperScript: { children: ["x"], subScript: ["i"], superScript: ["2"] } },
],
},
},
],
},
},
],
},
],
});
JSON:
{ "subScript": { "children": ["x"], "subScript": ["i"] } }
{ "superScript": { "children": ["x"], "superScript": ["2"] } }
{ "subSuperScript": { "children": ["x"], "subScript": ["i"], "superScript": ["2"] } }
MathSum / MathIntegral
import { generateDocument } from "@office-open/docx";
await generateDocument({
sections: [
{
children: [
{
paragraph: {
children: [
{
math: {
children: [
{ sum: { children: ["x"], subScript: ["i=0"], superScript: ["n"] } },
{ integral: { children: ["f(x)"], subScript: ["a"], superScript: ["b"] } },
],
},
},
],
},
},
],
},
],
});
JSON:
{ "sum": { "children": ["x"], "subScript": ["i=0"], "superScript": ["n"] } }
{ "integral": { "children": ["f(x)"], "subScript": ["a"], "superScript": ["b"] } }
MathLimitLower / MathLimitUpper
import { generateDocument } from "@office-open/docx";
await generateDocument({
sections: [
{
children: [
{
paragraph: {
children: [
{
math: {
children: [{ limitLower: { children: ["lim"], limit: ["x→0"] } }],
},
},
],
},
},
],
},
],
});
JSON:
{ "limitLower": { "children": ["lim"], "limit": ["x→0"] } }
MathFunction
import { generateDocument } from "@office-open/docx";
await generateDocument({
sections: [
{
children: [
{
paragraph: {
children: [
{
math: {
children: [{ function: { name: ["sin"], children: ["x"] } }],
},
},
],
},
},
],
},
],
});
JSON:
{ "function": { "name": ["sin"], "children": ["x"] } }
MathMatrix
import { generateDocument } from "@office-open/docx";
await generateDocument({
sections: [
{
children: [
{
paragraph: {
children: [
{
math: {
children: [
{
matrix: {
rows: [
["a", "b"],
["c", "d"],
],
},
},
],
},
},
],
},
},
],
},
],
});
JSON:
{
"matrix": {
"rows": [
["a", "b"],
["c", "d"]
]
}
}
Brackets
All bracket types produce m:d delimiter elements with different characters:
import { generateDocument } from "@office-open/docx";
await generateDocument({
sections: [
{
children: [
{
paragraph: {
children: [
{
math: {
children: [
{ roundBrackets: ["x + y"] },
{ squareBrackets: ["x"] },
{ curlyBrackets: ["a", "b"] },
{ angledBrackets: ["x"] },
],
},
},
],
},
},
],
},
],
});
JSON:
{ "roundBrackets": ["x + y"] }
{ "squareBrackets": ["x"] }
{ "curlyBrackets": ["a", "b"] }
{ "angledBrackets": ["x"] }
Math Accent
Accents (hat, tilde, etc.):
import { generateDocument } from "@office-open/docx";
await generateDocument({
sections: [
{
children: [
{
paragraph: {
children: [
{
math: {
children: [{ accent: { children: ["x"], accentCharacter: "^" } }],
},
},
],
},
},
],
},
],
});
JSON:
{ "accent": { "children": ["x"], "accentCharacter": "^" } }
Math Bar
Overline/underline bars:
import { generateDocument } from "@office-open/docx";
await generateDocument({
sections: [
{
children: [
{
paragraph: {
children: [
{
math: {
children: [
{ bar: { children: ["x"], type: "top" } }, // "top" or "bot"
],
},
},
],
},
},
],
},
],
});
JSON:
{ "bar": { "children": ["x"], "type": "top" } }
MathEqArr
Equation array for aligned equations:
import { generateDocument } from "@office-open/docx";
await generateDocument({
sections: [
{
children: [
{
paragraph: {
children: [
{
math: {
children: [
{
eqArr: {
rows: [
["a", "=", "b + c"],
["d", "=", "e + f"],
],
},
},
],
},
},
],
},
},
],
},
],
});
JSON:
{
"eqArr": {
"rows": [
["a", "=", "b + c"],
["d", "=", "e + f"]
]
}
}
MathBorderBox
Draw a border box around an expression with configurable borders and strikethroughs:
import { generateDocument } from "@office-open/docx";
await generateDocument({
sections: [
{
children: [
{
paragraph: {
children: [
{
math: {
children: [
{ borderBox: { children: ["a"] } },
// Hide top and bottom borders
{
borderBox: {
children: ["b"],
hideTop: true,
hideBottom: true,
},
},
],
},
},
],
},
},
],
},
],
});
JSON:
{ "borderBox": { "children": ["a"] } }
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:
import { generateDocument } from "@office-open/docx";
await generateDocument({
sections: [
{
children: [
{
paragraph: {
children: [
{
math: {
children: [{ box: { children: ["x + y"], opEmu: true } }],
},
},
],
},
},
],
},
],
});
JSON:
{ "box": { "children": ["x + y"] } }
MathGroupChr
Add a grouping character (brace, bracket, etc.) above or below content:
import { generateDocument } from "@office-open/docx";
await generateDocument({
sections: [
{
children: [
{
paragraph: {
children: [
{
math: {
children: [
{
groupChr: {
children: [{ eqArr: { rows: [["a"], ["b"]] } }],
chr: "{",
pos: "bot",
vertJc: "top",
},
},
],
},
},
],
},
},
],
},
],
});
JSON:
{ "groupChr": { "children": ["a", "b"] } }
MathPhantom
Create invisible placeholders for spacing control:
import { generateDocument } from "@office-open/docx";
await generateDocument({
sections: [
{
children: [
{
paragraph: {
children: [
{
math: {
children: [{ phant: { children: ["dy"], zeroAsc: true, zeroDesc: true } }],
},
},
],
},
},
],
},
],
});
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:
{
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:
{
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:
{
"sections": [
{
"children": [
{
"paragraph": {
"children": [
"Arrow: ",
{ "symbolRun": { "char": "F021", "symbolfont": "Wingdings" } },
" check: ",
{ "symbolRun": { "char": "F052", "symbolfont": "Wingdings" } }
]
}
}
]
}
]
}
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.):
import { generateDocument } from "@office-open/docx";
await generateDocument({
sections: [
{
children: [
{
paragraph: {
children: [
{
ruby: {
base: "漢字",
text: "かんじ",
},
},
{
ruby: {
base: "汉字",
text: "hànzì",
language: "zh-CN",
},
},
],
},
},
],
},
],
});
Ruby Options
| Property | Type | Description |
|---|---|---|
base | string | Base text to annotate |
text | string | Ruby annotation text |
alignment | "left" | "center" | "right" | Alignment (default: "center") |
rubyFontSize | number | Font size in points |
offset | number | Vertical offset in half-points |
language | string | Language identifier (e.g., "ja-JP") |