`<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 models

See appendix for information about this element in OASIS document type shells.

Inheritance

- topic/xref

Examples

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.