| -api-id | -api-type |
|---|---|
T:Windows.UI.Xaml.Controls.HyperlinkButton |
winrt class |
Represents a button control that functions as a hyperlink.
<HyperlinkButton .../>
-or-
<HyperlinkButton>stringContent</HyperlinkButton>
-or-
<HyperlinkButton>
singleObject
</HyperlinkButton>
HyperlinkButton is a button that appears as marked up text.
Note
By default, the HyperlinkButton appears as underlined text when you set a string as the value for the Content property.
The text does not appear underlined in the following cases:
- You set a TextBlock as the value for the Content property, and set the Text property on the TextBlock.
- You re-template the HyperlinkButton and change the name of the ContentPresenter template part. If you need a button that appears as non-underlined text, consider using a standard Button control and applying the built-in TextBlockButtonStyle system resource to its Style property.
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. For more info, see Hyperlink.
- 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.
To use the hyperlink to navigate to a Uniform Resource Identifier (URI), set the NavigateUri property. When a user clicks or taps the HyperlinkButton, 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 HyperlinkButton, 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 HyperlinkButton 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.
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 WebView control that also exists in your app, call WebView.Navigate 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.
You can modify the default Style and ControlTemplate to give the control a unique appearance. For information about modifying a control's style and template, see Styling controls. The default style, template, and resources that define the look of the control are included in the generic.xaml file. For design purposes, generic.xaml is available locally with the SDK or NuGet package installation.
- WinUI Styles (recommended): For updated styles from WinUI, see
\Users\<username>\.nuget\packages\microsoft.ui.xaml\<version>\lib\uap10.0\Microsoft.UI.Xaml\Themes\generic.xaml. - Non-WinUI styles: For built-in styles, see
%ProgramFiles(x86)%\Windows Kits\10\DesignTime\CommonConfiguration\Neutral\UAP\<SDK version>\Generic\generic.xaml.
Locations might be different if you customized the installation. Styles and resources from different versions of the SDK might have different values.
XAML also includes resources that you can use to modify the colors of a control in different visual states without modifying the control template. Modifying these resources is preferred to setting properties such as Background and Foreground. For more info, see the Light-weight styling section of the XAML styles article. Light-weight styling resources are available starting in Windows 10, version 1607 (SDK 14393).
Tip
For more info, design guidance, and code examples, see Hyperlink button.
[!div class="nextstepaction"] Open the WinUI 2 Gallery app and see the HyperlinkButton in action
The WinUI 2 Gallery app includes interactive examples of most WinUI 2 controls, features, and functionality. Get the app from the Microsoft Store or get the source code on GitHub.
Here's a HyperlinkButton as declared in XAML. It declares a string value for Content and also a NavigateUri value.
[!code-xamlBasicHyperlinkButtonXAML]