Skip to content
BlazorUI

Utilities

Link

Bit.BlazorUIAnchor

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.

Usage

Every example is live. Open its code to see exactly what produced the component running underneath.

Basic

An Href and a text are all a link needs. It takes the size and weight of whatever it sits in, so inside a sentence it matches the words around it. A disabled link loses its href and can no longer be followed.

Read the bit platform source on GitHub.
Basic link Disabled link

Underline

The underline appears under the pointer by default. Underlined keeps it at every state - the right choice inside body text. NoUnderline removes it at every state and wins when both are set; keep it for places that already read as links, such as a menu.

Underlined on hover (default) Always underlined Never underlined

Icon

IconName adds a glyph sized to the text beside it; IconPlacement moves it after the text. The icon is hidden from screen readers, so the text has to say what it says.

Leading icon Trailing icon

New tab

Target takes any browsing context (BitLinkTarget names the standard ones). A _blank link gets rel="noopener" and a visually hidden "(opens in a new tab)" for screen readers. NewTabHint rewords or translates it; NoNewTabHint drops it where the page already says so.

Opens in a new tab(opens in a new tab) Announced with a translated hint(در زبانه جدید باز می‌شود) GitHub (opens in a new tab)

Download

Download saves the file instead of opening it: empty keeps the server's file name, a value suggests one. Browsers honor it for same-origin, blob: and data: URLs only.

Download the bit logo Download with a custom file name

Rel

Rel combines BitLinkRels flags with |. It stays on a disabled link, since it describes the link rather than how it behaves; an in-page (#) link ignores it.

nofollow noreferrer sponsored ugc opener (no automatic noopener)(opens in a new tab)

Events

Without an Href the link is a button and OnClick is its action; with one, OnClick runs alongside the navigation. StopPropagation keeps the click from a clickable container, and PreventDefault cancels the navigation but keeps the href for a middle click or "copy link address".

An anchor with OnClick (clicked 0 times) (opens in a new tab)
A clickable container (clicked 0 times):
Ask before leaving

In-page links

An Href starting with # smooth-scrolls the element with that id into view and moves the focus there, without touching the address bar. The scroll jumps instead under reduced motion; a scroll-margin on the target element keeps it clear of a fixed header.

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

Current link

Match follows the URL like Blazor's NavLink: while the Href matches the page, the link gets aria-current="page" and keeps its underline, so the current one is not told apart by color alone. Exact matches the page itself, Prefix every page under it too.



AriaCurrent sets it by hand where there is no URL to follow - Step in a wizard, Location in a breadcrumb. With a Match, it only picks the kind.

Accessibility

Title is a hover-only tooltip, so it only adds to what the text says. AriaDescription is read after the link's name - the place for a file's size or format.

Hover for the full address Download the brand guidelines SVG, 12 kilobytes


A disabled link leaves the tab order. AllowDisabledFocus keeps it focusable with aria-disabled, so keyboard and screen reader users still find it. FocusAsync moves the focus onto a link from code, and AutoFocus does it on the first render.

Disabled (skipped by Tab) Disabled (still focusable) The focus lands here

CSS variables

The public --bit-Link-* variables inherit, so one set on :root or a container restyles every link inside it, and one set in Style restyles that link. They win over Color and Size. A current link drawn in a weight of its own no longer needs the underline to stand out.

Set on the container: an offset, thicker underline, and a visited link in its own color.
Set on one link

Cascading parameters

BitParams with a BitLinkParams sets defaults for every link under it - say, a translated NewTabHint for a whole app. A link's own value wins (the last one opts out of Underlined).

bit platform(opens in a new tab) bit platform on GitHub(opens in a new tab) Its own Underlined, the cascaded rest(opens in a new tab)

Color

Color picks a role, Primary by default. Accent roles use the role's readable text shade, so every color keeps its contrast on the page. NoColor drops the link color for content that brings its own.

Primary Secondary Tertiary Info Success Warning SevereWarning Error

PrimaryBackground SecondaryBackground TertiaryBackground

PrimaryForeground SecondaryForeground TertiaryForeground PrimaryBorder SecondaryBorder TertiaryBorder

Disabled:

Primary Secondary Warning Error PrimaryForeground

NoColor:

A card-like link

Its text keeps the colors BitText gives it.

External Icons

Icon takes a BitIconInfo for external sets like FontAwesome and Bootstrap Icons, sized and colored like the link text.

FontAwesome FontAwesome, trailing(opens in a new tab) Bootstrap Bootstrap, trailing(opens in a new tab)

Size

Unset, a link takes the font size around it. Size is for a link that stands on its own; the icon follows it.

Small Medium Large

Style & Class

The link is one element, so Style and Class are all it takes to restyle it.

Link with style Link with class

RTL

Dir set to BitDir.Rtl lays the link out right to left; a leading icon stays on the leading side.

پیوند راست به چپ پیوند راست به چپ با آیکن

CSS variables

The public custom properties this component reads off its root, for what no parameter covers.

Every variable is read with a fallback and never declared by the component, so it inherits like any other custom property: set one on :root (or in a [bit-theme] block) to restyle every instance, on any ancestor to restyle the ones inside it, or on the Style of one instance to restyle that one alone. Leave a variable unset and the component falls back to the theme token beside it.

BitLink CSS variables

Name Default value Description
--bit-Link-color from the Color role Text color at rest. Wins over the Color parameter.
--bit-Link-hover-color from the Color role Text color under the pointer and while focused from the keyboard.
--bit-Link-active-color from the Color role Text color while pressed.
--bit-Link-visited-color --bit-Link-color Text color of a link whose destination was already visited.
--bit-Link-disabled-color from the Color role Text color and focus ring color of a disabled link.
--bit-Link-current-color --bit-Link-color Text color of the current link (aria-current, or a Match on the URL) at rest.
--bit-Link-focus-color from the Color role Color of the keyboard focus ring.
--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. Wins over the Size parameter.
--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.

API

Every parameter, public member, sub-class and enum this component exposes.

BitLink 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.
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.
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 says otherwise) 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.

BitLink 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.

BitComponentBase parameters

Name Type Default value Description
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.
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.

BitComponentBase public members

Name Type Default value Description
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.

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.

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.

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.

Feedback

Found a mistake, a gap, or something that could be clearer? Every page and every component is one click from its source.