Hyperlink Class

Reference

Definition

Namespace:: Microsoft.UI.Xaml.Documents

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Edit

Provides an inline-level content element that provides facilities for hosting hyperlinks.

public ref class Hyperlink sealed : Span

/// [Windows.Foundation.Metadata.Activatable(65536, "Microsoft.UI.Xaml.WinUIContract")]
/// [Windows.Foundation.Metadata.ContractVersion(Microsoft.UI.Xaml.WinUIContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class Hyperlink final : Span

[Windows.Foundation.Metadata.Activatable(65536, "Microsoft.UI.Xaml.WinUIContract")]
[Windows.Foundation.Metadata.ContractVersion(typeof(Microsoft.UI.Xaml.WinUIContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public sealed class Hyperlink : Span

Public NotInheritable Class Hyperlink
Inherits Span

<Hyperlink .../>

Inheritance: Object Platform::Object IInspectable DependencyObject TextElement Inline Span Hyperlink

Attributes: ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Examples

Here's an example of a simple Hyperlink element in a TextBlock.

In XAML, the creation of content elements is implicit, so you can add the link text directly to the Hyperlink, and the Hyperlink directly to the TextBlock element.

In code, you have to explicitly create each Run element, set its Text property, and add it to the appropriate Inlines collection (either the Hyperlink or the TextBlock).

<TextBlock><Hyperlink NavigateUri="http://www.bing.com">Go to Bing</Hyperlink></TextBlock>

// Create a TextBlock. The hyperlink is the TextBlock content. 
TextBlock tb = new TextBlock();

// Create a Hyperlink and a Run. 
// The Run provides the visible content of the hyperlink. 
Hyperlink hyperlink = new Hyperlink();
Run run = new Run();

// Set the Text property on the Run. This will be the visible text of the hyperlink.
run.Text = "Go to Bing";
// Set the URI for the Hyperlink. 
hyperlink.NavigateUri = new Uri("http://www.bing.com");

// Add the Run to Hyperlink.Inlines collection.
hyperlink.Inlines.Add(run);
// Add the text elements to the TextBlock.Inlines collection.
tb.Inlines.Add(hyperlink);
// Add the TextBlock to a StackPanel (defined in the XAML page).        
stackPanel.Children.Add(tb);

This example shows a Hyperlink element in a TextBlock with other text.

In XAML, the creation of content elements is implicit, so you can add the link text directly to the Hyperlink. The Span element with the xml:space="preserve" attribute is used to preserve white space around the hyperlink.

In code, you have to explicitly create each Run element, set its Text property, and add it to the appropriate Inlines collection (either the Hyperlink or the TextBlock).

<TextBlock>
    <Span xml:space="preserve"><Run>Open </Run><Hyperlink NavigateUri="http://www.bing.com">Bing</Hyperlink><Run> in your browser.</Run></Span>
</TextBlock>

// Create a TextBlock. The hyperlink is part of the TextBlock content. 
// Set TextWrapping so that the text and the hyperlink wrap if the content is too wide.
TextBlock tb = new TextBlock();
tb.TextWrapping = TextWrapping.Wrap;

// Create a Hyperlink and a Run. 
// The Run provides the visible content of the hyperlink. 
Hyperlink hyperlink = new Hyperlink();
Run run = new Run();
// Set the Text property on the Run. This will be the visible text of the hyperlink.
run.Text = "Bing";
// Set the URI for the Hyperlink. 
hyperlink.NavigateUri = new Uri("http://www.bing.com");
//Add the Run to Hyperlink.Inlines collection.
hyperlink.Inlines.Add(run);

// Create Run elements for the text around the hyperlink.
Run run1 = new Run();
Run run2 = new Run();            
//Set the Text property on the Run elements.
run1.Text = "Open ";
run2.Text = " in your browser.";

// Add the text elements to the TextBlock.Inlines collection.
tb.Inlines.Add(run1);
tb.Inlines.Add(hyperlink);
tb.Inlines.Add(run2);

// Add the TextBlock to a StackPanel (defined in the XAML page).        
stackPanel.Children.Add(tb);

Here's an example of a simple Hyperlink element in a TextBlock.

In XAML, the creation of content elements is implicit, so you can add the link text directly to the Hyperlink, and the Hyperlink directly to the TextBlock element. The Span element with the xml:space="preserve" attribute is used to preserve white space around the hyperlink.

In code, you have to explicitly create each text element (for example, Run, Paragraph, or Italic) and add it to the appropriate Inlines collection.

<RichTextBlock>
    <Paragraph>
        <Span xml:space="preserve">
            <Run>This shows a hyperlink in a paragraph of text. You can click it to open </Run><Hyperlink NavigateUri="http://www.bing.com" UnderlineStyle="None" FontWeight="SemiBold"><Italic>Bing</Italic></Hyperlink><Run> in your browser.</Run>
        </Span>
    </Paragraph>
</RichTextBlock>

// Create a RichTextBlock. The hyperlink is part of the content. 
// Set TextWrapping so that the text and the hyperlink wrap if the content is too wide.
RichTextBlock rtb = new RichTextBlock();
rtb.TextWrapping = TextWrapping.Wrap;

// Create a Hyperlink and a Run. 
// The Run provides the visible content of the hyperlink. 
Hyperlink hyperlink = new Hyperlink();
Run run = new Run();
// Set the Text property on the Run. This will be the visible text of the hyperlink.
run.Text = "Bing";
// Set the URI  and other properties for the Hyperlink. 
hyperlink.NavigateUri = new Uri("http://www.bing.com");
hyperlink.UnderlineStyle = UnderlineStyle.None;
hyperlink.FontWeight = Windows.UI.Text.FontWeights.SemiBold;
//Add the Run to Hyperlink.Inlines collection.
hyperlink.Inlines.Add(run);


// Create an Italic element for the hyperlink.            
Italic italic = new Italic();
italic.Inlines.Add(hyperlink);

// Create Run elements for the text around the hyperlinks.
// Set the Text property on the Run elements.
Run run1 = new Run();
Run run2 = new Run();
run1.Text = "This shows a hyperlink in a paragraph of text. You can click it to open ";
run2.Text = " in your browser.";

// Create a Paragraph to hold the RichTextBlock content.
Paragraph paragraph = new Paragraph();

// Add the text elements to the Paragraph.Inlines collection.
paragraph.Inlines.Add(run1);
paragraph.Inlines.Add(italic);
paragraph.Inlines.Add(run2);
//Add the paragraph to the RichTextBlock.
rtb.Blocks.Add(paragraph);
// Add the RichTextBlock to a StackPanel (defined in the XAML page).        
stackPanel.Children.Add(rtb);

Remarks

Hyperlink and HyperlinkButton

There are two ways that you can add a hyperlink to a XAML app. Hyperlink and HyperlinkButton have the similar purpose of enabling a user to launch a specific URI using a separate browser app.+ Use an inline Hyperlink text element inside of a text control. A Hyperlink element flows with other text elements and you can use it in any InlineCollection.

Use a HyperlinkButton control anywhere in the app. A HyperlinkButton is a specialized Button control that you can use anywhere that you would use a Button. For more info, see HyperlinkButton.

Inline hyperlink

You use the Hyperlink element to add interactive text to the content of a TextBlock or RichTextBlock. Hyperlink is derived from the Inline class, so you can place it inside of any container that has an InlineCollection as its Inlines property, such as TextBlock, Paragraph, or Span.

Tip

When you use a Hyperlink within a Span container with other text elements in XAML, apply the xml:space="preserve" attribute to the Span to keep the white space between the Hyperlink and other elements.

Navigate to a URI

To use the hyperlink to navigate to a Uniform Resource Identifier (URI), set the NavigateUri property. When a user clicks or taps the Hyperlink element, the specified Uniform Resource Identifier (URI) opens in the default browser. The default browser runs in a separate process from your app.

Tip

You don't have to use http: or https: schemes. You can use schemes such as ms-appx:, ms-appdata:, or ms-resources:, if there's resource content at these locations that's appropriate to load in a browser. However, the file: scheme is specifically blocked. For more info, see URI schemes.

When a user clicks the Hyperlink, the value of the NavigateUri property is passed to a system handler for Uniform Resource Identifier (URI) types and schemes. The system then launches the app that is registered for the scheme of the Uniform Resource Identifier (URI) provided for NavigateUri.

If you don't want the Hyperlink to load content in a default Web browser (and don't want a browser to appear), then don't set a value for NavigateUri. Instead, handle the Click event, and write code that does what you want.

Handle the Click event

Use the Click event for actions other than launching a Uniform Resource Identifier (URI) in a browser, such as navigation within the app. For example, if you want to load a new app page rather than opening a browser, call a Frame.Navigate method within your Click event handler to navigate to the new app page. If you want an external, absolute Uniform Resource Identifier (URI) to load within a WebView2 control that also exists in your app, call WebView2.NavigateToString(System.String) as part of your Click handler logic.

You don't typically handle the Click event as well as specifying a NavigateUri value, as these represent two different ways of using the Hyperlink element. If your intent is to open the URI in the default browser, and you have specified a value for NavigateUri, don't handle the Click event. Conversely, if you handle the Click event, don't specify a NavigateUri.

There's nothing you can do within the Click event handler to prevent the default browser from loading any valid target specified for NavigateUri; that action takes place automatically (asynchronously) when the hyperlink is activated and can't be canceled from within the Click event handler.

Hyperlink limitations

Because a Hyperlink is not a UIElement, it does not have the set of UI element input events such as Tapped, PointerPressed and so on. Instead, a Hyperlink has its own Click event, plus the implicit behavior of the system loading any Uniform Resource Identifier (URI) specified as the NavigateUri. The system handles all input actions that should invoke the Hyperlink actions and raises the Click event in response.

Hyperlink has restrictions on the content that can exist in its Inlines collection. Specifically, a Hyperlink only permits Run and other Span types that aren't another Hyperlink. InlineUIContainer can't be in the Inlines collection of a Hyperlink. Attempting to add restricted content throws an invalid argument exception or XAML parse exception.

Hyperlink and theme/style behavior

Hyperlink doesn't inherit from Control, so it doesn't have a Style property or a Template. You can edit the properties that are inherited from TextElement, such as Foreground or FontFamily, to change the appearance of a Hyperlink, but you can't use a common style or template to apply changes. Instead of using a template, consider using common resources for values of Hyperlink properties to provide consistency. Some properties of Hyperlink use defaults from a {ThemeResource} markup extension value provided by the system. This enables the Hyperlink appearance to switch in appropriate ways when the user changes the system theme at run-time.

The default color of the hyperlink is the accent color of the system. You can set the Foreground property to override this.

By default, Hyperlink is underlined. This underline is important because it helps meet accessibility requirements. Color-blind users use the underline to distinguish between hyperlinks and other text. You can set the UnderlineStyle property to disable the underline. If you disable underlines, you should consider adding some other type of formatting difference to distinguish hyperlinks from other text, such as FontWeight or FontStyle.

Constructors

Hyperlink()

Initializes a new instance of the Hyperlink class.

Properties

AccessKey	Gets or sets the access key for this element. (Inherited from TextElement)
AccessKeyScopeOwner	Gets or sets a source element that provides the access key scope for this element, even if it's not in the visual tree of the source element. (Inherited from TextElement)
AllowFocusOnInteraction	Gets or sets a value that indicates whether the element automatically gets focus when the user interacts with it. (Inherited from TextElement)
CharacterSpacing	Gets or sets the uniform spacing between characters, in units of 1/1000 of an em. (Inherited from TextElement)
ContentEnd	Gets a TextPointer that represents the end of the content in the element. (Inherited from TextElement)
ContentStart	Gets a TextPointer that represents the start of content in the element. (Inherited from TextElement)
Dispatcher	Always returns `null` in a Windows App SDK app. Use DispatcherQueue instead. (Inherited from DependencyObject)
DispatcherQueue	Gets the `DispatcherQueue` that this object is associated with. The `DispatcherQueue` represents a facility that can access the `DependencyObject` on the UI thread even if the code is initiated by a non-UI thread. (Inherited from DependencyObject)
ElementEnd	Gets a TextPointer that represents the position just after the end of the element. (Inherited from TextElement)
ElementSoundMode	Gets or sets a value that specifies the control's preference for whether it plays sounds.
ElementSoundModeProperty	Identifies the ElementSoundMode dependency property.
ElementStart	Gets a TextPointer that represents the position just before the start of the element. (Inherited from TextElement)
ExitDisplayModeOnAccessKeyInvoked	Gets or sets a value that specifies whether the access key display is dismissed when an access key is invoked. (Inherited from TextElement)
FocusState	Gets a value that specifies whether this hyperlink has focus, and the mode by which focus was obtained.
FocusStateProperty	Identifies the FocusState dependency property.
FontFamily	Gets or sets the preferred top-level font family for the content of the element. (Inherited from TextElement)
FontSize	Gets or sets the font size for the content of the element. (Inherited from TextElement)
FontStretch	Gets or sets the glyph width of the font in a family to select. (Inherited from TextElement)
FontStyle	Gets or sets the font style for the content in this element. (Inherited from TextElement)
FontWeight	Gets or sets the top-level font weight to select from the font family for the content in this element. (Inherited from TextElement)
Foreground	Gets or sets the Brush to apply to the content in this element. (Inherited from TextElement)
Inlines	Gets an InlineCollection containing the top-level inline elements that include the contents of Span. (Inherited from Span)
IsAccessKeyScope	Gets or sets a value that indicates whether an element defines its own access key scope. (Inherited from TextElement)
IsTabStop	Gets or sets a value that indicates whether the hyperlink is included in tab navigation.
IsTabStopProperty	Identifies the IsTabStop dependency property.
IsTextScaleFactorEnabled	Gets or sets whether automatic text enlargement, to reflect the system text size setting, is enabled. (Inherited from TextElement)
KeyTipHorizontalOffset	Gets or sets a value that indicates how far left or right the keytip is placed in relation to the text element. (Inherited from TextElement)
KeyTipPlacementMode	Gets or sets a value that indicates where the KeyTip is placed in relation to the text element. (Inherited from TextElement)
KeyTipVerticalOffset	Gets or sets a value that indicates how far up or down the keytip is placed in relation to the text element. (Inherited from TextElement)
Language	Gets or sets localization/globalization language information that applies to a TextElement. (Inherited from TextElement)
Name	Gets or sets a unique identification for the object. Name can only be set from initial parsing of XAML. (Inherited from TextElement)
NavigateUri	Gets or sets the Uniform Resource Identifier (URI) to navigate to when the Hyperlink is activated.
NavigateUriProperty	Identifies the NavigateUri dependency property.
TabIndex	Gets or sets a value that determines the order in which elements receive focus when the user navigates through controls by pressing the Tab key.
TabIndexProperty	Identifies the TabIndex dependency property.
TextDecorations	Gets or sets a value that indicates what decorations are applied to the text. (Inherited from TextElement)
UnderlineStyle	Gets or sets a value that indicates what kind of underline is shown under the hyperlink.
UnderlineStyleProperty	Identifies the UnderlineStyle dependency property.
XamlRoot	Gets or sets the XamlRoot in which this element is being viewed. (Inherited from TextElement)
XYFocusDown	Gets or sets the object that gets focus when a user presses the Directional Pad (DPAD) down.
XYFocusDownNavigationStrategy	Gets or sets a value that specifies the strategy used to determine the target element of a down navigation.
XYFocusDownNavigationStrategyProperty	Identifies the XYFocusDownNavigationStrategy dependency property.
XYFocusDownProperty	Identifies the XYFocusDown dependency property.
XYFocusLeft	Gets or sets the object that gets focus when a user presses the Directional Pad (DPAD) left.
XYFocusLeftNavigationStrategy	Gets or sets a value that specifies the strategy used to determine the target element of a left navigation.
XYFocusLeftNavigationStrategyProperty	Identifies the XYFocusLeftNavigationStrategy dependency property.
XYFocusLeftProperty	Identifies the XYFocusLeft dependency property.
XYFocusRight	Gets or sets the object that gets focus when a user presses the Directional Pad (DPAD) right.
XYFocusRightNavigationStrategy	Gets or sets a value that specifies the strategy used to determine the target element of a right navigation.
XYFocusRightNavigationStrategyProperty	Identifies the XYFocusRightNavigationStrategy dependency property.
XYFocusRightProperty	Identifies the XYFocusRight dependency property.
XYFocusUp	Gets or sets the object that gets focus when a user presses the Directional Pad (DPAD) up.
XYFocusUpNavigationStrategy	Gets or sets a value that specifies the strategy used to determine the target element of an up navigation.
XYFocusUpNavigationStrategyProperty	Identifies the XYFocusUpNavigationStrategy dependency property.
XYFocusUpProperty	Identifies the XYFocusUp dependency property.

Methods

ClearValue(DependencyProperty)	Clears the local value of a dependency property. (Inherited from DependencyObject)
FindName(String)	Retrieves an object in the object model / runtime object graph by referencing the object's x:Name or Name attribute value. (Inherited from TextElement)
Focus(FocusState)	Attempts to set the focus on the hyperlink.
GetAnimationBaseValue(DependencyProperty)	Returns any base value established for a dependency property, which would apply in cases where an animation is not active. (Inherited from DependencyObject)
GetValue(DependencyProperty)	Returns the current effective value of a dependency property from a DependencyObject. (Inherited from DependencyObject)
OnDisconnectVisualChildren()	Override this method to implement how layout and logic should behave when items are removed from a class-specific content or child property. (Inherited from TextElement)
ReadLocalValue(DependencyProperty)	Returns the local value of a dependency property, if a local value is set. (Inherited from DependencyObject)
RegisterPropertyChangedCallback(DependencyProperty, DependencyPropertyChangedCallback)	Registers a notification function for listening to changes to a specific DependencyProperty on this DependencyObject instance. (Inherited from DependencyObject)
SetValue(DependencyProperty, Object)	Sets the local value of a dependency property on a DependencyObject. (Inherited from DependencyObject)
UnregisterPropertyChangedCallback(DependencyProperty, Int64)	Cancels a change notification that was previously registered by calling RegisterPropertyChangedCallback. (Inherited from DependencyObject)

Events

AccessKeyDisplayDismissed	Occurs when the access key sequence is complete to notify controls that they should hide access key visuals. (Inherited from TextElement)
AccessKeyDisplayRequested	Occurs when the access key sequence is started to notify controls that they should show access key visuals. (Inherited from TextElement)
AccessKeyInvoked	Occurs when a user completes an access key sequence to notify the element that the access key action should be invoked. (Inherited from TextElement)
Click	Occurs when the Hyperlink is clicked.
GotFocus	Occurs when a Hyperlink receives focus.
LostFocus	Occurs when a Hyperlink loses focus.

Applies to

Share via