`<xref>`

Use the <xref> element to provide an inline cross reference. It is commonly used to link to a different location within the current topic, a different topic, a specific location in another topic, or an external resource. The target of the cross-reference is specified using the @href or @keyref attributes.

When creating a cross-reference, link to the element structure, not the <title> element of the object. For example, to create a cross-reference to a figure, link to the <fig> element, not the <title> element within the <fig> element. Output processing determines whether the text of the <title> element is used to render the cross-reference.

Cross references that link to elements in other topics can employ key-based addressing by using the @keyref attribute. This enables the cross-reference to point to different topics in the context of different top-level maps. Cross references that employ direct URI-based addressing using the @href attribute create dependencies; if the topic with the cross-reference is included in a map, the target topic also might need to be included for the cross-reference to be resolvable in the context of that map. While you can use conditional processing to have different cross-references for different contexts, it is usually easier and more effective to use keys. By using keys, the cross-reference can be independent of the contexts it might be used in, because it is up to each different map to bind the key used by the cross-reference to the appropriate target.

In many cases it is best to avoid inline cross references in favor of links of links that are generated by the related-links element or relationship tables. Such links typically are rendered at the end of the topic. This prevents readers from leaving a topic and missing important information. Using relationship tables also enables the links to be managed at a DITA map level, making it possible for topics to be quickly integrated into new contexts without breaking links.

Content model

Contained by

<abstract>, <area>, <b>, <bodydiv>, <data>, <dd>, <desc>, <div>, <draft-comment>, <dt>, <entry>, <example>, <fig>, <figgroup>, <fn>, <howtoavoid>, <i>, <itemgroup>, <li>, <line-through>, <lines>, <linkinfo>, <lq>, <note>, <overline>, <p>, <ph>, <pre>, <q>, <section>, <sectiondiv>, <shortdesc>, <sli>, <stentry>, <sub>, <sup>, <tt>, <u>

Zero or more of the following

Text
<boolean>
<cite>
<data>
<data-about>
<desc>
<draft-comment>
<foreign>
<image>
<keyword>
<ph>
<q>
<required-cleanup>
<state>
<term>
<text>
<tm>
<unknown>

Contained by

<abstract>
<area>
<b>
<bodydiv>
<data>
<dd>
<desc>
<div>
<draft-comment>
<dt>
<entry>
<example>
<fig>
<figgroup>
<fn>
<howtoavoid>
<i>
<itemgroup>
<li>
<line-through>
<lines>
<linkinfo>
<lq>
<note>
<overline>
<p>
<ph>
<pre>
<q>
<section>
<sectiondiv>
<shortdesc>
<sli>
<stentry>
<sub>
<sup>
<tt>
<u>

Inheritance

- topic/xref

The <xref> element is a base element type. It is defined in the topic module.

Examples

This section is non-normative.

This example shows a cross-reference to another topic; that topic's title will typically be used as the link text.
```
<p>Background information about DITA is provided in the topic entitled
<xref href="whatsdita.dita"></xref>.</p>
```
The same cross reference could be created using @keyref instead of @href; using @keyref allows the link to be redirected to different resources when used in different map contexts.
```
<p>Background information about DITA is provided in the topic entitled
<xref keyref="whatisdita"></xref>.</p>
```

This example shows cross-references to another topic; the supplied text will be used as the link text:

<p><xref href="whatsdita.dita#tmmdita">Background information about
DITA</xref> is provided free of charge. For a context free cross reference,
the keyref attribute can also link to a topic for <xref keyref="whatisdita">information
 about DITA</xref>.</p>

If you are linking to an element inside of a topic, use the following format in the @href attribute:
```
filename.dita#topicid/elementid
```
The @keyref attribute can also be used to link to an element inside of a topic; in this case the key represents the topic, but the element ID remains the same:
```
keyname/elementid
```
If you are linking within the same file, you can leave off the file name portion filename.dita. So, for a section with the ID "mysection", use:
```
#topicid/mysection  
```
Alternatively, if the link is to an element within the same topic you can use:
```
#./mysection
```
For a list item within that section, assuming the item has an ID of "mylist", use:
```
#topicid/mylist  
```
Alternatively, because the link is to an element within the same topic, you can use:
```
#./mylist
```

See DITA addressing for details on using URI references and Indirect key-based addressing for details on using key references.

If your URL has an ampersand (&) in it, you need to code that using a entity reference. For example, this URL includes an & character:

http://www.example.com/docview.wss?rs=757&context=SSVNX5

When used in an @href attribute, the ampersand must be entered as & as shown here:

<xref href="http://www.example.com/docview.wss?rs=757&amp;context=SSVNX5"
scope="external">Part number SSVNX5</xref>

Attributes

The following attributes are available on this element: Universal attribute group, Link relationship attribute group, outputclass, and @keyref.