Skip to content
# Link **Also known as:** Anchor ## Description BitLink renders an anchor when it has an Href and a button when it does not, so a link that runs a command still answers the keyboard like a button. An Href starting with # scrolls to its target and moves the focus there, and a Match follows the URL to mark the current link. A new-tab link gets a noopener rel and an announcement that it opens a new tab. It is restyled through its parameters, its public CSS variables or a BitParams cascade. ## Notes A link goes somewhere and a button does something: reach for BitButton or BitActionButton when the action changes the page rather than leaving it. Inside a sentence, keep a link Underlined - color alone does not tell every reader it is a link. ## Parameters | Name | Type | Default Value | Description | | :--- | :--- | :------------ | :---------- | | AllowDisabledFocus | `bool` | false | Keeps a disabled link in the tab order, conveying the disabled state through aria-disabled instead. | | AriaCurrent | `BitNavAriaCurrent?` | null | Reports the link as the current item of the set it belongs to, through the aria-current attribute, and keeps it underlined at rest. With a Match, the URL decides whether the link is current and this only which kind (Page when not set). | | AriaDescription | `string?` | null | Visually hidden text the link points at through aria-describedby, read after its name - the place for a file's size or format. | | AutoFocus | `bool` | false | Gives the link the focus on its first render, in static and interactive rendering alike. A disabled link only takes it with AllowDisabledFocus. | | ChildContent | `RenderFragment?` | null | The content of the link, can be any custom tag or a text. | | Color | `BitColor?` | null | The general color of the link, Primary when not set. Accent colors use the role's readable text shade. An explicit value wins over the --bit-Link-* color variables; left unset, the link is primary unless they say otherwise. | | Download | `string?` | null | Makes the browser save the linked resource instead of opening it; a value suggests the file name. Honored for same-origin, blob: and data: URLs only. | | Href | `string?` | null | The URL the link points to; without one the link renders a button. A value starting with # scrolls the element with that id into view and moves the focus there. | | Icon | `BitIconInfo?` | null | An icon from an external library (FontAwesome, Bootstrap Icons, ...) rendered beside the content. Wins over IconName. | | IconName | `string?` | null | The name of a built-in Fluent UI icon rendered beside the content. The icon is hidden from assistive technologies. | | IconPlacement | `BitPlacement?` | null | Where the icon sits: before the content (default) or after it (End). | | Match | `BitNavMatch?` | null | Follows the current URL like Blazor's NavLink: while the Href matches it, the link renders aria-current (the AriaCurrent kind, page when not set) and stays underlined. Exact matches the page, Prefix every page under it too; Regex and Wildcard read the Href as the pattern. In-page (#) links never match. | | NewTabHint | `string?` | null | Replaces the visually hidden "(opens in a new tab)" a _blank link is announced with, e.g. to translate it. An empty value removes it. | | NoColor | `bool` | false | Drops the link color, so the content keeps its own. | | NoNewTabHint | `bool` | false | Stops a _blank link from announcing that it opens a new tab. Only for where the page already says so. | | NoUnderline | `bool` | false | Removes the underline at every state. Wins over Underlined. | | OnClick | `EventCallback<MouseEventArgs>` | | Invoked on click: alongside the navigation on an anchor, as the whole action on a button (no Href). | | PreventDefault | `bool` | false | Cancels the navigation of a click, leaving OnClick as the whole action. The href stays, so a middle click and "copy link address" still work. | | Rel | `BitLinkRels?` | null | The relationship to the linked document, as combinable flags. Ignored for # hrefs. A _blank link without NoOpener, NoReferrer or Opener gets noopener added. | | Size | `BitSize?` | null | The preset text size. Unset, the link takes the font size of whatever it sits in. An explicit value wins over --bit-Link-font-size; left unset, the link inherits its font size unless it says otherwise. | | StopPropagation | `bool` | false | Stops the click from reaching the parent elements, e.g. a clickable row or card. | | Target | `string?` | null | Where to open the link, e.g. _blank for a new tab - which also adds noopener (unless Rel already says NoOpener, NoReferrer or Opener) and the new-tab announcement. | | Title | `string?` | null | A tooltip shown on hover. Touch and the keyboard never reach it, so it only adds to what the text says. | | Underlined | `bool` | false | Keeps the underline at every state - the right choice inside body text. | | AriaLabel | `string?` | null | Gets or sets the accessible label for the component, used by assistive technologies. | | Class | `string?` | null | Gets or sets the CSS class name(s) to apply to the rendered element. | | Dir | `BitDir?` | null | Gets or sets the text directionality for the component's content. | | Disabled | `bool` | false | Gets or sets a value indicating whether the component is disabled and cannot respond to user interaction. | | ForceAnimation | `bool` | false | Gets or sets a value indicating whether the component's animations play at their full duration even when reduced motion is requested. | | HtmlAttributes | `Dictionary<string, object>` | new Dictionary<string, object>() | Captures additional HTML attributes to be applied to the rendered element, in addition to the component's parameters. An attribute written on the component wins over an entry of the same name. | | Id | `string?` | null | Gets or sets the unique identifier for the component's root element. | | Style | `string?` | null | Gets or sets the CSS style string to apply to the rendered element. | | TabIndex | `string?` | null | Gets or sets the tab order index for the component when navigating with the keyboard. | | Visibility | `BitVisibility` | BitVisibility.Visible | Gets or sets the visibility state (visible, hidden, or collapsed) of the component. | ## Public Members | Name | Type | Default Value | Description | | :--- | :--- | :------------ | :---------- | | FocusAsync | `ValueTask` | | Moves the focus onto the link. A disabled link only takes it with AllowDisabledFocus. | | FocusAsync(bool preventScroll) | `ValueTask` | | Moves the focus onto the link; true keeps the page scrolled where it is. | | UniqueId | `Guid` | Guid.NewGuid() | Gets the readonly unique identifier for the component's root element, assigned when the component instance is constructed. | | RootElement | `ElementReference` | | Gets the reference to the root HTML element associated with this component. | ## Enums ### BitColor Enum | Name | Value | Description | | :--- | :--- | :---------- | | Primary | 0 | Primary general color. | | Secondary | 1 | Secondary general color. | | Tertiary | 2 | Tertiary general color. | | Info | 3 | Info general color. | | Success | 4 | Success general color. | | Warning | 5 | Warning general color. | | SevereWarning | 6 | SevereWarning general color. | | Error | 7 | Error general color. | | PrimaryBackground | 8 | Primary background color. | | SecondaryBackground | 9 | Secondary background color. | | TertiaryBackground | 10 | Tertiary background color. | | PrimaryForeground | 11 | Primary foreground color. | | SecondaryForeground | 12 | Secondary foreground color. | | TertiaryForeground | 13 | Tertiary foreground color. | | PrimaryBorder | 14 | Primary border color. | | SecondaryBorder | 15 | Secondary border color. | | TertiaryBorder | 16 | Tertiary border color. | ### BitNavAriaCurrent Enum | Name | Value | Description | | :--- | :--- | :---------- | | Page | 0 | Represents the current page within a set of pages. | | Step | 1 | Represents the current step within a process. | | Location | 2 | Represents the current location within an environment or context. | | Date | 3 | Represents the current date within a collection of dates. | | Time | 4 | Represents the current time within a set of times. | | True | 5 | Represents the current item within a set, without saying which kind of set it is. | ### BitNavMatch Enum | Name | Value | Description | | :--- | :--- | :---------- | | Exact | 0 | Matches the page the Href points at. The case, a trailing slash and a query the Href does not carry are ignored. | | Prefix | 1 | Matches the page the Href points at and every page under it. | | Regex | 2 | Reads the Href as a regular expression matched against the current URL. | | Wildcard | 3 | Reads the Href as a wildcard pattern (* within a segment, ** across segments) matched against the current URL. | ### BitPlacement Enum | Name | Value | Description | | :--- | :--- | :---------- | | Top | 0 | The top edge. | | Bottom | 1 | The bottom edge. | | Start | 2 | The edge the reading direction starts from - the left in LTR, the right in RTL. On the vertical axis, which does not turn around, it is the top. | | End | 3 | The edge the reading direction ends at - the right in LTR, the left in RTL. On the vertical axis, which does not turn around, it is the bottom. | | Left | 4 | The left edge, in both reading directions. | | Right | 5 | The right edge, in both reading directions. | | Center | 6 | The middle of the axis, against neither edge. | | TopAndBottom | 7 | Both edges of the block axis at once. | | StartAndEnd | 8 | Both edges of the inline axis at once, following the reading direction the way Start and End do. | ### BitSize Enum | Name | Value | Description | | :--- | :--- | :---------- | | Small | 0 | The small size. | | Medium | 1 | The medium size. | | Large | 2 | The large size. | ### BitLinkRels Enum | Name | Value | Description | | :--- | :--- | :---------- | | Alternate | 1 | Provides a link to an alternate representation of the document. (i.e. print page, translated or mirror) | | Author | 2 | Provides a link to the author of the document. | | Bookmark | 4 | Permanent URL used for bookmarking. | | External | 8 | Indicates that the referenced document is not part of the same site as the current document. | | Help | 16 | Provides a link to a help document. | | License | 32 | Provides a link to licensing information for the document. | | Next | 64 | Provides a link to the next document in the series. | | NoFollow | 128 | Links to an unendorsed document, like a paid link. ("NoFollow" is used by Google, to specify that the Google search spider should not follow that link) | | NoOpener | 256 | Requires that any browsing context created by following the hyperlink must not have an opener browsing context. | | NoReferrer | 512 | Makes the referrer unknown. No referrer header will be included when the user clicks the hyperlink. | | Prev | 1024 | The previous document in a selection. | | Search | 2048 | Links to a search tool for the document. | | Tag | 4096 | A tag (keyword) for the current document. | | Me | 8192 | Indicates that the linked document represents the person who owns the current content. (used for identity verification) | | Opener | 16384 | Requires that any browsing context created by following the hyperlink keeps its opener browsing context. (reverses the implicit noopener modern browsers apply to _blank targets) | | PrivacyPolicy | 32768 | Links to the privacy policy that applies to the current document. (rendered as privacy-policy) | | Sponsored | 65536 | Marks the link as an advertisement or paid placement, so search engines do not count it as an organic endorsement. | | TermsOfService | 131072 | Links to the terms of service that apply to the current document. (rendered as terms-of-service) | | Ugc | 262144 | Marks the link as user-generated content, like forum posts or comments, for search engines. | ### BitVisibility Enum | Name | Value | Description | | :--- | :--- | :---------- | | Visible | 0 | The content of the component is visible. | | Hidden | 1 | The content of the component is hidden, but the space it takes on the page remains (visibility:hidden). | | Collapsed | 2 | The component is hidden (display:none). | ### BitDir Enum | Name | Value | Description | | :--- | :--- | :---------- | | Ltr | 0 | Ltr (left to right) is to be used for languages that are written from the left to the right (like English). | | Rtl | 1 | Rtl (right to left) is to be used for languages that are written from the right to the left (like Arabic). | | Auto | 2 | Auto lets the user agent decide. It uses a basic algorithm as it parses the characters inside the element until it finds a character with a strong directionality, then applies that directionality to the whole element. | ## Sub Classes ### BitLinkTarget Properties | Name | Type | Default Value | Description | | :--- | :--- | :------------ | :---------- | | Self | `` | _self | The current browsing context. (Default) | | Blank | `` | _blank | Usually a new tab, but users can configure browsers to open a new window instead. | | Parent | `` | _parent | The parent browsing context of the current one. If no parent, behaves as _self. | | Top | `` | _top | The topmost browsing context. To be specific, this means the 'highest' context that's an ancestor of the current one. If no ancestors, behaves as _self. | | UnfencedTop | `` | _unfencedTop | Allows embedded fenced frames to navigate the top-level frame. | ## CSS Variables Public CSS custom properties read off the component's root. Set one on `:root` to restyle every instance, on any ancestor to restyle the ones inside it, or on the `Style` of one instance to restyle it and every instance nested inside it, which inherits the value too - a parameter changes one alone, as does the real CSS property on its `Style` / `Styles` when that property does not inherit (`opacity`); an inherited one (`color`, `font-family`) reaches the nested instances that do not set it themselves. | Name | Default Value | Description | | :--- | :------------ | :---------- | | `--bit-Link-color` | --bit-clr-pri | Text color at rest. The Color parameter wins over it. | | `--bit-Link-hover-color` | --bit-clr-pri-hover | Text color under the pointer and while focused from the keyboard. The Color parameter wins over it. | | `--bit-Link-active-color` | --bit-clr-pri-active | Text color while pressed. The Color parameter wins over it. | | `--bit-Link-visited-color` | --bit-Link-color | Text color of a link whose destination was already visited. The Color parameter wins over it. | | `--bit-Link-disabled-color` | --bit-clr-pri-dis-text | Text color and focus ring color of a disabled link. The Color parameter wins over it. | | `--bit-Link-current-color` | --bit-Link-color | Text color of the current link (aria-current, or a Match on the URL) at rest. The Color parameter wins over it. | | `--bit-Link-focus-color` | --bit-clr-pri-focus | Color of the keyboard focus ring. The Color parameter wins over it. While it is unset, the focus ring is the library's own --bit-shd-focus-ring, so replacing that token re-shapes it too. | | `--bit-Link-font-family` | --bit-tpg-font-family | Typeface of the text. Set it to inherit where a link has to match the typeface around it. | | `--bit-Link-font-size` | inherit | Size of the text. The Size parameter wins over it. | | `--bit-Link-font-weight` | inherit | Weight of the text. | | `--bit-Link-current-font-weight` | --bit-Link-font-weight | Weight of the text of the current link. | | `--bit-Link-underline-color` | currentColor | Color of the underline. | | `--bit-Link-underline-thickness` | auto | Thickness of the underline. | | `--bit-Link-underline-offset` | auto | Gap between the text and its underline. | | `--bit-Link-icon-gap` | spacing(0.375) (3px) | Room between the icon and the text. | | `--bit-Link-radius` | --bit-shp-radius-control | Corner radius of the focus ring. | ## Examples \n**Basic**: ```razor
Read the bit platform source on GitHub.
Basic link Disabled link ``` \n**Underline**: ```razor Underlined on hover (default) Always underlined Never underlined ``` \n**Icon**: ```razor Leading icon Trailing icon ``` \n**New tab**: ```razor Opens in a new tab Announced with a translated hint GitHub (opens in a new tab) ``` \n**Download**: ```razor Download the bit logo Download with a custom file name ``` \n**Rel**: ```razor nofollow noreferrer sponsored ugc opener (no automatic noopener) ``` \n**Events**: ```razor A button link (clicked @buttonClickCount times) An anchor with OnClick (clicked @anchorClickCount times)
A clickable container (clicked @containerClickCount times): StopPropagation (clicked @innerClickCount times)
Ask before leaving
@guardMessage
``` ```csharp private int buttonClickCount; private int anchorClickCount; private int innerClickCount; private int containerClickCount; private string? guardMessage; private void HandleGuardedClick() { // The browser did not navigate, so what happens next is entirely up to this handler: // confirm, save a draft, track the click, and then navigate from here if it should happen. guardMessage = "The navigation was suppressed. This is where a confirmation would go."; } ``` \n**In-page links**: ```razor Go to the end of the article

Every story starts with a blank canvas, a quiet space waiting to be filled with ideas, emotions and dreams. These placeholder words stand for the beginning, a moment where everything is still to come.

Soon these lines will turn into narratives that provoke thought and resonate with those who read them. Until then they are the scaffolding of something remarkable, a bridge between the empty page of now and the stories of tomorrow.

In this space potential reigns: each word can still become something extraordinary. Whether it is a tale of adventure, a reflection of truth or an idea that sparks change, these lines are yours to fill.

Back to the start of the article ``` \n**Current link**: ```razor
    @for (var i = 0; i < checkoutSteps.Length; i++) { var step = i;
  1. @checkoutSteps[step]
  2. }
``` ```csharp private int currentStep; private readonly string[] checkoutSteps = ["Cart", "Shipping", "Payment"]; ``` \n**Accessibility**: ```razor Hover for the full address Download the brand guidelines Disabled (skipped by Tab) Disabled (still focusable) Focus the link below The focus lands here ``` ```csharp private BitLink focusTargetRef = default!; ``` \n**CSS variables**: ```razor
Set on the container: an offset, thicker underline, and a visited link in its own color.
Set on one link ``` \n**Cascading parameters**: ```razor bit platform bit platform on GitHub Its own Underlined, the cascaded rest ``` ```csharp private readonly BitLinkParams[] linkParams = [ new() { Underlined = true, Target = BitLinkTarget.Blank, IconName = BitIconName.OpenInNewWindow, IconPlacement = BitPlacement.End, } ]; ``` \n**Color**: ```razor Primary Secondary Tertiary Info Success Warning SevereWarning Error
PrimaryBackground SecondaryBackground TertiaryBackground
PrimaryForeground SecondaryForeground TertiaryForeground PrimaryBorder SecondaryBorder TertiaryBorder Primary Secondary Warning Error PrimaryForeground A card-like link Its text keeps the colors BitText gives it. ``` \n**External Icons**: ```razor FontAwesome FontAwesome, trailing Bootstrap Bootstrap, trailing ``` \n**Size**: ```razor Small Medium Large ``` \n**Style & Class**: ```razor Link with style Link with class ``` \n**RTL**: ```razor
پیوند راست به چپ پیوند راست به چپ با آیکن
```