# Hyperlink

The following functionality is supported in the **RadRichTextEditor**:

* having a hyperlink span several paragraphs;

* being able to embed all kinds of elements inside hyperlinks, e.g. images, tables, and table elements;

* making bookmarks in the document the targets of hyperlinks.

The classes that encapsulate the functionality of hyperlinks are [HyperlinkInfo](https://www.telerik.com/products/winforms/documentation/controls/richtexteditor/features/hyperlink#hyperlinkinfo),[HyperlinkRangeStart and HyperlinkRangeEnd](https://www.telerik.com/products/winforms/documentation/controls/richtexteditor/features/hyperlink#hyperlinkrangestart-and-hyperlinkrangeend).

[Other customization options](https://www.telerik.com/products/winforms/documentation/controls/richtexteditor/features/hyperlink#other-customization-options) include setting the tooltip format and detecting the click of hyperlinks.

## HyperlinkInfo

More often than not, you would only need to use objects of type **HyperlinkInfo**. **HyperlinkInfo** objects have the following properties:

* **IsAnchor** - a Boolean property determining if the hyperlink points to a URL or a bookmark;

* **NavigateUri** - the URI of the hyperlink;

* **Target** - determines if the link should be opened in another window (if set to HyperlinkTargets.*Blank*) or in the same frame (HyperlinkTargets.*Self*).

For example, a link to our site can be inserted in the document programmatically as follows:

```C#
HyperlinkInfo info = new HyperlinkInfo()
{
    NavigateUri = "http://www.telerik.com",
    Target = HyperlinkTargets.Blank,
    IsAnchor = false
};
this.radRichTextEditor1.InsertHyperlink(info, "RichTextBox demo");

```

```VB.NET
Dim info As New HyperlinkInfo() With {.NavigateUri = "http://www.telerik.com", .Target = HyperlinkTargets.Blank, .IsAnchor = False}
Me.radRichTextEditor1.InsertHyperlink(info, "RichTextBox demo")

```

A link to a bookmark is inserted by specifying the bookmark's name as **NavigateUri** and setting the **IsAnchor** property to *true*:

```C#
this.radRichTextEditor1.RemoveHyperlink();

```

```VB.NET
Me.radRichTextEditor1.RemoveHyperlink()

```

You can also use the overloaded methods for inserting a hyperlink:

* public void **InsertHyperlink**(HyperlinkInfo hyperlinkInfo, string hyperlinkText, StyleDefinition hyperlinkStyle) - insert a hyperlink using a custom style, different from the default blue font color and single underline;

* public void **InsertHyperlink**(HyperlinkInfo hyperlinkInfo, IEnumerable\<Inline> inlines) - insert a hyperlink which spans several different adjacent inlines, e.g. part of the hyperlink text is bold or there is an image inside the hyperlink;

* public void **InsertHyperlink**(HyperlinkInfo hyperlinkInfo) - create a hyperlink from the currently selected part of the document;

* public void **InsertHyperlink**(HyperlinkInfo hyperlinkInfo, StyleDefinition hyperlinkStyle) - create a hyperlink from the currently selected part of the document and change the style of the text to the style passed as second argument.

Removing a hyperlink (and keeping the part of the document that the hyperlink spanned) can be done by positioning the caret in the hyperlink and invoking:

```C#
this.radRichTextEditor1.RemoveHyperlink();

```

```VB.NET
Me.radRichTextEditor1.RemoveHyperlink()

```

## HyperlinkRangeStart and HyperlinkRangeEnd

**HyperlinkRangeStart** and **HyperlinkRangeEnd** are **Inline** DocumentElements and can be added to the inlines of a document, if you are building the contents of a **RadDocument** in code-behind.

Here is an example that creates a document with a hyperlink spanning several paragraphs, including an image in one of the paragraphs:

```C#
HyperlinkRangeStart hyperlinkStart = new HyperlinkRangeStart();
HyperlinkRangeEnd hyperlinkEnd = new HyperlinkRangeEnd();
hyperlinkEnd.PairWithStart(hyperlinkStart);
HyperlinkInfo hyperlinkInfo = new HyperlinkInfo() { NavigateUri = "http://telerik.com", Target = HyperlinkTargets.Blank };
hyperlinkStart.HyperlinkInfo = hyperlinkInfo;
RadDocument document = new RadDocument();
Section section = new Section();
Paragraph paragraph = new Paragraph();
Span spanBefore = new Span("Text before the image ");
ImageInline image;
using (MemoryStream ms = new MemoryStream())
{
    System.Drawing.Image.FromFile(@"C:\logo.png").Save(ms, System.Drawing.Imaging.ImageFormat.Png);
    image = new ImageInline(ms, new Telerik.WinControls.RichTextEditor.UI.Size(25, 25), "png");
}
Span spanAfter = new Span(" and some text after the image");
paragraph.Inlines.Add(hyperlinkStart);
paragraph.Inlines.Add(spanBefore);
paragraph.Inlines.Add(image);
paragraph.Inlines.Add(spanAfter);
section.Blocks.Add(paragraph);
Paragraph anotherParagraph = new Paragraph();
anotherParagraph.Inlines.Add(new Span("Another paragraph here and still in hyperlink"));
anotherParagraph.Inlines.Add(hyperlinkEnd);
section.Blocks.Add(anotherParagraph);
document.Sections.Add(section);
this.radRichTextEditor1.Document = document;

```

```VB.NET
Dim hyperlinkStart As New HyperlinkRangeStart()
Dim hyperlinkEnd As New HyperlinkRangeEnd()
hyperlinkEnd.PairWithStart(hyperlinkStart)
Dim hyperlinkInfo As New HyperlinkInfo() With {.NavigateUri = "http://telerik.com", .Target = HyperlinkTargets.Blank}
hyperlinkStart.HyperlinkInfo = hyperlinkInfo
Dim document As New RadDocument()
Dim section As New Section()
Dim paragraph As New Paragraph()
Dim spanBefore As New Span("Text before the image ")
Dim image As ImageInline
Using ms As New MemoryStream()
    System.Drawing.Image.FromFile("C:\logo.png").Save(ms, System.Drawing.Imaging.ImageFormat.Png)
    image = New ImageInline(ms, New Telerik.WinControls.RichTextEditor.UI.Size(25, 25), "png")
End Using
Dim spanAfter As New Span(" and some text after the image")
paragraph.Inlines.Add(hyperlinkStart)
paragraph.Inlines.Add(spanBefore)
paragraph.Inlines.Add(image)
paragraph.Inlines.Add(spanAfter)
section.Blocks.Add(paragraph)
Dim anotherParagraph As New Paragraph()
anotherParagraph.Inlines.Add(New Span("Another paragraph here and still in hyperlink"))
anotherParagraph.Inlines.Add(hyperlinkEnd)
section.Blocks.Add(anotherParagraph)
document.Sections.Add(section)
Me.radRichTextEditor1.Document = document

```

The result (`Ctrl` + `Click` to follow):

![WinForms RadRichTextEditor Hyperlink Review](https://www.telerik.com/products/winforms/documentation/assets/f853f94fb814a17675caa79ebb418900/richtexteditor-features-hyperlink001.png)

You will also need to use **HyperlinkRangeStart** and **HyperlinkRangeEnd**, if you are using hyperlinks for the implementation of custom logic and want to get all hyperlinks from the document, manipulate the properties of the **HyperlinkInfo** or the whole part of the document that is included in the hyperlink.

For instance, here is how you can delete all hyperlinks in the document and replace them with some text:

```C#
IEnumerable<HyperlinkRangeStart> links = this.radRichTextEditor1.Document.EnumerateChildrenOfType<HyperlinkRangeStart>();
foreach (HyperlinkRangeStart link in links)
{
    this.radRichTextEditor1.Document.CaretPosition.MoveToInline(link.FirstLayoutBox as Telerik.WinForms.Documents.Layout.InlineLayoutBox, 0);
    this.radRichTextEditor1.Document.Selection.SelectAnnotationRange(link);
    this.radRichTextEditor1.Delete(false);
    this.radRichTextEditor1.Insert("Removed hyperlink");
}
```

```VB.NET
Dim links As IEnumerable(Of HyperlinkRangeStart) = Me.radRichTextEditor1.Document.EnumerateChildrenOfType(Of HyperlinkRangeStart)()
For Each link As HyperlinkRangeStart In links
    Me.radRichTextEditor1.Document.CaretPosition.MoveToInline(TryCast(link.FirstLayoutBox, Telerik.WinForms.Documents.Layout.InlineLayoutBox), 0)
    Me.radRichTextEditor1.Document.Selection.SelectAnnotationRange(link)
    Me.radRichTextEditor1.Delete(False)
    Me.radRichTextEditor1.Insert("Removed hyperlink")
Next link
```

## Other Customization Options

### ToolTip

By default, hyperlinks take a fixed string as a tooltip. The default format is:

> note "{0}{1} to follow link" - The first parameter is the URL, and the second is "Ctrl + Click" which is taken from the localization file.

You have control over it using the **HyperlinkToolTipFormatString** of **RadRichTextEditor**, which will set the format for all hyperlinks in the document.

### HyperlinkClicked event

When a hyperlink is clicked, the **HyperlinkClicked** event of **RadRichTextEditor** is fired. The sender of the event is the document element, that you have clicked, e.g. a **Span**, an **Image**, **InlineUIContainer**, etc. The **HyperlinkClickedEventArgs** provides the possibility either to cancel or replace the navigation action. This is helpful when you need to validate the clicked hyperlink and prevent it from navigating to an unsecured address or from starting a local process.

Since 2024 Q3 (2024.3.924), external-link navigation validates the destination before opening it. External links must pass both `HyperlinkHelper.ValidateLinkPattern` and `HyperlinkHelper.ValidateLinkScheme`; the default schemes are absolute `http`, `https`, and `mailto`. This external-link validation predates the shared hyperlink event integration.

`Telerik.WinForms.Documents.Model.HyperlinkClickedEventArgs` inherits `URL`, `Handled`, and `IsTrustedUrl` from `Telerik.WinControls.Hyperlinks.HyperlinkClickedEventArgs` and retains `HyperlinkTarget`. Set `IsTrustedUrl` to `true` only after applying application-specific destination checks. Set `Handled` to `true` to suppress or replace navigation.

After the local event, an unhandled request reaches `HyperlinkHelper.HyperlinkClicked`, where a global policy can also change the trust state. See [shared hyperlink validation](https://www.telerik.com/products/winforms/documentation/telerik-presentation-framework/html-like-text-formatting#shared-hyperlink-validation) for both checks and [handling links across controls](https://www.telerik.com/products/winforms/documentation/telerik-presentation-framework/html-like-text-formatting#handling-links-across-controls) for a global approval example.

Here is an example of using the HyperlinkClicked event prompting that the clicked hyperlink might be unsafe and allows to cancel the navigation process upon receiving the end user confirmation:

```C#
void radRichTextEditor1_HyperlinkClicked(object sender, HyperlinkClickedEventArgs e)
{
    e.Handled = false;
}
```

```VB.NET
Private Sub radRichTextEditor1_HyperlinkClicked(ByVal sender As Object, ByVal e As HyperlinkClickedEventArgs)
    e.Handled = False
End Sub
```

### HyperlinkNavigationMode

The **HyperlinkNavigationMode** allows you to control what action should trigger the opening of a hyperlink. The possible options are:

* **CtrlClick**: Triggers the hyperlink when users hold the Ctrl key and click on the hyperlink.
* **Click**: Triggers the hyperlink when users click on the hyperlink.

Below is demonstrated how to change the default hyperlink navigation mode:

```C#
this.radRichTextEditor1.HyperlinkNavigationMode = Telerik.WinForms.Documents.UI.HyperlinkNavigationMode.Click;
```

```VB.NET
Me.radRichTextEditor1.HyperlinkNavigationMode = Telerik.WinForms.Documents.UI.HyperlinkNavigationMode.Click

```

## See Also

* [Document Elements](https://www.telerik.com/products/winforms/documentation/controls/richtexteditor/document-elements/overview)

* [RadDocument](https://www.telerik.com/products/winforms/documentation/controls/richtexteditor/document-elements/raddocument)

* [Inline Image](https://www.telerik.com/products/winforms/documentation/controls/richtexteditor/document-elements/inline-image)