XML
Query Utilities
Traverse and inspect parsed XML Element trees with helper functions
After parsing XML with parse(), use these utilities to traverse and extract data from the Element tree.
Finding Children
findChild
Find the first direct child by tag name:
import { parse, findChild } from "@office-open/xml";
const root = parse("<w:p><w:r><w:t>Hello</w:t></w:r></w:p>");
const run = findChild(root, "w:r");
children
Get all direct children matching a tag name:
import { parse, children } from "@office-open/xml";
const root = parse("<w:p><w:r/><w:r/><w:r/></w:p>");
const runs = children(root, "w:r"); // 3 elements
allChildren
Get all direct children regardless of tag name:
import { allChildren } from "@office-open/xml";
const all = allChildren(root);
Reading Text
childText
Get text content of the first matching child:
import { parse, findChild, childText } from "@office-open/xml";
const root = parse("<w:p><w:r><w:t>Hello</w:t></w:r></w:p>");
const text = childText(root, "w:t"); // "Hello"
textOf
Get text content of an element itself:
import { textOf } from "@office-open/xml";
const textEl = findChild(run, "w:t");
const text = textOf(textEl); // "Hello"
collectText
Collect text from all text nodes in an element and its descendants:
import { collectText } from "@office-open/xml";
const allText = collectText(paragraph); // Concatenated text content
Reading Attributes
attr
Get attribute value as string:
import { parse, findChild, attr } from "@office-open/xml";
const element = parse('<w:spacing w:before="240" w:after="120"/>');
attr(element, "w:before"); // "240"
attr(element, "w:after"); // "120"
attrNum
Get attribute value as number:
attrNum(element, "w:before"); // 240
attrBool
Get attribute value as boolean:
attrBool(element, "w:val"); // true or false based on "true"/"1"/"false"/"0"
colorAttr
Get hex color attribute with normalization:
import { colorAttr } from "@office-open/xml";
colorAttr(element, "w:color"); // "FF0000"
Checking Structure
hasChild
Check if an element has a specific child:
import { hasChild } from "@office-open/xml";
hasChild(paragraph, "w:pPr"); // true or false
findDeep
Find all descendant elements matching a tag name:
import { findDeep } from "@office-open/xml";
const allTextNodes = findDeep(document, "w:t");
childCount
Get the number of direct child elements:
import { childCount } from "@office-open/xml";
childCount(paragraph); // 3
Complete Reference
| Function | Returns | Description |
|---|---|---|
findChild(parent, name) | Element | undefined | First direct child by name |
children(parent, name) | Element[] | All direct children by name |
allChildren(parent) | Element[] | All direct children |
childText(parent, name) | string | Text of first matching child |
textOf(element) | string | Text content of element |
collectText(element) | string | All text from descendants |
attr(element, name) | string | undefined | Attribute as string |
attrNum(element, name) | number | undefined | Attribute as number |
attrBool(element, name) | boolean | undefined | Attribute as boolean |
colorAttr(element, name) | string | undefined | Hex color attribute |
hasChild(parent, name) | boolean | Child exists check |
findDeep(parent, name) | Element[] | All descendants by name |
childCount(parent) | number | Direct child count |