Links

Add navigation to your documents with hyperlinks and bookmarks.

#External Hyperlinks

Link to external URLs:

JSON

{
  "sections": [
    {
      "children": [
        {
          "paragraph": {
            "children": [
              {
                "hyperlink": {
                  "url": "https://example.com",
                  "children": [
                    {
                      "text": "Visit example.com",
                      "color": "0563C1",
                      "underline": { "type": "single" }
                    }
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

TypeScript

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

await generateDocument({
  sections: [
    {
      children: [
        {
          paragraph: {
            children: [
              {
                hyperlink: {
                  url: "https://example.com",
                  children: [
                    {
                      text: "Visit example.com",
                      underline: { type: "single" },
                      color: "0563C1",
                    },
                  ],
                },
              },
            ],
          },
        },
      ],
    },
  ],
});

#Internal Hyperlinks

Link to bookmarks within the same document using hyperlink with anchor:

JSON

{
  "sections": [
    {
      "children": [
        {
          "paragraph": {
            "children": [
              {
                "hyperlink": {
                  "anchor": "section-intro",
                  "children": [{ "text": "Go to Introduction", "color": "0563C1" }]
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

TypeScript

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

await generateDocument({
  sections: [
    {
      children: [
        {
          paragraph: {
            children: [
              {
                hyperlink: {
                  anchor: "section-intro",
                  children: [{ text: "Go to Introduction", color: "0563C1" }],
                },
              },
            ],
          },
        },
      ],
    },
  ],
});

#Bookmarks

Define a bookmark with the bookmark child, placed inline around the text it marks:

JSON

{
  "sections": [
    {
      "children": [
        {
          "paragraph": {
            "children": [
              {
                "bookmark": { "name": "section-intro", "wrap": ["Introduction"] }
              }
            ]
          }
        }
      ]
    }
  ]
}

TypeScript

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

await generateDocument({
  sections: [
    {
      children: [
        {
          paragraph: {
            children: [{ bookmark: { name: "section-intro", wrap: ["Introduction"] } }],
          },
        },
      ],
    },
  ],
});

wrap is the anchored document content the bookmark range wraps (inline runs/text).

Property	Type	Description
`name`	`string`	Bookmark name (the reference handle)
`wrap`	`(string \| RunOptions)[]`	Anchored text the bookmark wraps
`colFirst`	`number`	First column of a table-cell scope
`colLast`	`number`	Last column of a table-cell scope
`displacedByCustomXml`	`"before" \| "after"`	Displacement vs. a sibling customXml

#Explicit markers (advanced)

For ranges that span paragraphs or tables, or to continue ids from an existing document, author the markers explicitly. The bookmarkStart and bookmarkEnd must share one id:

TypeScript

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

await generateDocument({
  sections: [
    {
      children: [
        {
          paragraph: {
            children: [
              { bookmarkStart: { name: "section-intro", id: 0 } },
              "Introduction",
              { bookmarkEnd: 0 },
            ],
          },
        },
      ],
    },
  ],
});

Use bookmarks with hyperlink (using anchor) for cross-referencing within a document. The anchor property references bookmark names.

#Screen Tips

Add a tooltip that appears on hover:

JSON

{
  "sections": [
    {
      "children": [
        {
          "paragraph": {
            "children": [
              {
                "hyperlink": {
                  "url": "https://example.com",
                  "tooltip": "Click to visit Example",
                  "children": [{ "text": "Example Link", "color": "0563C1" }]
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

TypeScript

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

await generateDocument({
  sections: [
    {
      children: [
        {
          paragraph: {
            children: [
              {
                hyperlink: {
                  url: "https://example.com",
                  tooltip: "Click to visit Example",
                  children: [{ text: "Example Link", color: "0563C1" }],
                },
              },
            ],
          },
        },
      ],
    },
  ],
});