w:hyperlink (Hyperlink)

Wraps inline content as a clickable hyperlink to an external URL or internal bookmark target.

Parent elements

Child elements

Description

w:hyperlink creates an inline hyperlink around one or more runs. It is defined in ECMA-376 Part 1 §17.16.22.

For external links, an r:id attribute references an OPC relationship of type hyperlink. For internal links (to a bookmark), use w:anchor instead. The element contains w:r children whose w:rStyle is typically set to Hyperlink (an underlined, blue character style).

Attributes

Attribute	Type	Possible Values	Description
`r:id`	`ST_RelationshipId`	A relationship ID referencing an external URL target.	Used for external hyperlinks.
`w:anchor`	`ST_String`	A bookmark name (`w:bookmarkStart/@w:name`).	Used for internal (same-document) links.
`w:history`	`ST_OnOff`	`true` / `false`	Adds the hyperlink URL to the browser/app history when activated.
`w:docLocation`	`ST_String`	Any string.	Identifies a location within the linked document (for cross-document links).

Examples

<!-- External link (r:id targets the relationship URL) -->
<w:hyperlink r:id="rId10" w:history="true">
  <w:r>
    <w:rPr><w:rStyle w:val="Hyperlink"/></w:rPr>
    <w:t>Visit the site</w:t>
  </w:r>
</w:hyperlink>

<!-- Internal link to bookmark -->
<w:hyperlink w:anchor="intro">
  <w:r><w:t>See Introduction</w:t></w:r>
</w:hyperlink>

// External link
string relId = mainPart.AddHyperlinkRelationship(
  new Uri("https://example.com"), true).Id;
new Hyperlink(
  new Run(
    new RunProperties(new RunStyle { Val = "Hyperlink" }),
    new Text("Visit the site")))
{ Id = relId, History = true };

// Internal link
new Hyperlink(
  new Run(new Text("See Introduction")))
{ Anchor = "intro" };

<!-- Email link (mailto: scheme) -->
<w:hyperlink r:id="rId11">
  <w:r>
    <w:rPr><w:rStyle w:val="Hyperlink"/></w:rPr>
    <w:t>Contact Us</w:t>
  </w:r>
</w:hyperlink>
<!-- Relationship target: mailto:info@example.com -->

<!-- Link with multiple runs (bold + text) -->
<w:hyperlink r:id="rId12">
  <w:r>
    <w:rPr><w:b/><w:rStyle w:val="Hyperlink"/></w:rPr>
    <w:t>Important</w:t>
  </w:r>
  <w:r>
    <w:rPr><w:rStyle w:val="Hyperlink"/></w:rPr>
    <w:t xml:space="preserve"> Document</w:t>
  </w:r>
</w:hyperlink>

// Email link
string emailRelId = mainPart.AddHyperlinkRelationship(
  new Uri("mailto:info@example.com"), true).Id;
new Hyperlink(
  new Run(
    new RunProperties(
      new RunStyle { Val = "Hyperlink" }),
    new Text("Contact Us")))
{ Id = emailRelId };

// Multi-run link
new Hyperlink(
  new Run(
    new RunProperties(
      new Bold(),
      new RunStyle { Val = "Hyperlink" }),
    new Text("Important")),
  new Run(
    new RunProperties(new RunStyle { Val = "Hyperlink" }),
    new Text(" Document")))
{ Id = relId };

<!-- Cross-document link (different file with anchor) -->
<w:hyperlink r:id="rId13" w:docLocation="Chapter2"/>
  <w:r>
    <w:rPr><w:rStyle w:val="Hyperlink"/></w:rPr>
    <w:t>See Chapter 2</w:t>
  </w:r>
</w:hyperlink>
<!-- Relationship might target: ../related/reference.docx -->

// Cross-document link
string crossDocRelId = mainPart.AddHyperlinkRelationship(
  new Uri("../related/reference.docx", UriKind.Relative), true).Id;
new Hyperlink(
  new Run(
    new RunProperties(new RunStyle { Val = "Hyperlink" }),
    new Text("See Chapter 2")))
{ Id = crossDocRelId, DocLocation = "Chapter2" };

Hyperlink Types

Type	Attribute	Target	Example
External URL	`r:id`	HTTP(S) URL in relationship	`r:id="rId10"` → https://example.com
Email	`r:id`	mailto: scheme in relationship	`r:id="rId11"` → mailto:user@example.com
Internal Bookmark	`w:anchor`	Bookmark name in same document	`w:anchor="Section1"`
Cross-Document	`r:id` + `w:docLocation`	File path + anchor	`r:id="rId12"` (path) + `w:docLocation="Chap2"`
File/UNC Path	`r:id`	File or UNC path in relationship	`r:id="rId13"` → file:///C:/docs/file.docx

Hyperlink Styling

Style Property	Purpose	Typical Value
`w:rStyle w:val="Hyperlink"`	Character style for unvisited links	Blue, underlined
`w:rStyle w:val="FollowedHyperlink"`	Character style for visited links	Purple, underlined
`w:u`	Custom underline (if not using style)	single, double, none
`w:color`	Text color override	0070C0 (blue), 954F72 (purple)

Notes

Relationship IDs: External hyperlinks use r:id (relationship ID) to reference URLs defined in document.xml.rels; this indirection allows URL changes without modifying the main document.
Bookmark requirement: Internal anchors (w:anchor) must reference an existing w:bookmarkStart/w:bookmarkEnd pair with matching w:name; missing bookmarks create broken links.
Styling convention: Use the Hyperlink character style for external links and FollowedHyperlink for visited; these are semantic styles and render appropriately.
Email links: Use mailto: scheme (e.g., mailto:user@example.com?subject=Hello) in the relationship URL for email links.
File links: Use file:/// scheme (UNC paths: \\server\share) for local files; relative paths are supported via relationships.
Cross-document links: Use w:docLocation to specify an anchor within a linked document; the anchor must exist in the target file.
Multiple runs: A hyperlink can contain multiple w:r elements; this allows varied formatting (bold title + normal text) within a single link.
Nested elements: Bookmarks can appear inside hyperlinks; this allows links to bookmark regions.
History attribute: w:history="true" adds URL to browser/app history; false does not (useful for generated links).
Accessibility: Always provide meaningful link text; empty or placeholder links (<w:hyperlink><w:r><w:t> </w:t></w:r></w:hyperlink>) are inaccessible.
URL encoding: Relationship URLs must be properly encoded; spaces become %20, special characters must be percent-encoded.
Performance: Excessive hyperlinks can increase file size; each unique link requires an entry in document.xml.rels.