Link

This documentation is currently being revised and is in beta status. Content may still change.

This component is being retested for accessibility. The full test is still pending and can only be completed after a release.

Synonyms: Hyperlink, Reference, Anchor

Description: The Link component renders a link optimized for accessibility. It supports various display variants with text, icons or a combination of both, and can be displayed as an inline element or block element.

Example

Standard link with text and optional icon:

<KolLink _href="https://example.com" _label="Example Link" _target="_blank" />

Accessibility

• The Link component is fully keyboard-accessible.
• The label (_label) is rendered as visible text and is available to all users.
• Icons can be displayed in addition to the label and visually clarify the link purpose.
• For hidden label texts (_hideLabel: true), a tooltip is automatically shown when focused or hovered.
• The _ariaCurrentValue attribute can be used to mark an active/current page (e.g. _ariaCurrentValue="page").
• The _ariaDescription attribute can be used to provide additional accessibility information.

Links and References

Usage

Keyboard Controls

Key	Function
Tab	Focuses the link element.
Enter	Opens the hyperlink.
Space	Opens the hyperlink (depending on browser and context).

Best Practices / Recommendations

• Descriptive link texts: Use descriptive link texts like "More information" instead of "Click here".
• Preserve context: Links should be understandable out-of-context, e.g. for screen reader users who navigate a list of links.
• Inline vs. Block: Use _inline: true (default) for links in body text. Use _inline: false for links to be displayed as standalone blocks.
• Use icons meaningfully: Icons should clarify the link purpose, e.g. a download icon for file links. The label remains primary.
• Use download attribute: Use _download for links to files to signal to the browser that a file should be downloaded: _download="filename.pdf".
• Make target clear: When a link opens a new window/tab (_target="_blank"), mention this in the label or with an icon.
• External vs. internal links: Icon conventions help users identify external links.
• Don't disable without reason: The _disabled attribute should only be used with good justification.

Use Cases

• Navigation in menus and navigation bars
• Links in body text and paragraphs
• Links to external resources and documentation
• Download links for files
• Breadcrumb navigation
• Links in tables and lists
• Call-to-action links

FAQ

How do I activate automatic detection of the current page (aria-current)? Use the setCurrentLocation() service from KoliBri. See the aria-current service section below.

When should I use _hideLabel: true? Use this when a meaningful icon is available and the label text should be hidden for space reasons, but still read by screen readers. The text is then displayed as a tooltip.

Can I display multiple icons? Yes, you can combine multiple icon classes via the _icons attribute.

Construction / Technical

Playground

Test the various properties of the Link component:

Icons

Tooltip Align

<KolLink _href="https://public-ui.github.io/en/docs" _label="KoliBri - Public UI" _target="_blank" />

Functionality (with Code)

Basic Link

A simple link with label and href:

<KolLink _href="https://example.com" _label="Example Link" _target="_blank" />

Link with Icon

Link with an icon that visually clarifies the link purpose:

Icons

<KolLink _href="https://example.com" _icons="kolicon-external" _label="With Icon" _target="_blank" />

Link Variations

Various display variants and states:

<KolLink _href="https://example.com" _label="Link Variation" _target="_blank" />

Download Link

Link with download functionality:

<KolLink _download="file.pdf" _href="https://example.com/file.pdf" _label="Download file" _target="_blank" />

Tooltip Alignment

Configure tooltip positioning (when _hideLabel: true):

Tooltip Align

<KolLink _hideLabel={true} _href="https://example.com" _icons="kolicon-external" _label="Icon only" _target="_blank" _tooltipAlign="top" />

ARIA Attributes and Accessibility

Extended accessibility configurations:

<KolLink _ariaCurrentValue="page" _ariaDescription="This is the current page" _href="/current-page" _label="Active page" _target="_blank" />

aria-current Service

For the Link component to automatically set an aria-current attribute, it must be notified via the setCurrentLocation() service which page is currently active:

import { setCurrentLocation } from '@public-ui/components';

/* Call on every page change: */
setCurrentLocation('/path/to/page');

The location string passed must correspond exactly to the _href attribute of the link.

Events

For handling events and callbacks see .

Event	Trigger	Value
click	The link is clicked	-

API

Properties

Property	Attribute	Description	Type	Default
_accessKey	_access-key	Defines the key combination that can be used to trigger or focus the component's interactive element.	string | undefined	undefined
_ariaControls	_aria-controls	Defines which elements are controlled by this component. (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls)	string | undefined	undefined
_ariaCurrentValue	_aria-current-value	Defines the value for the aria-current attribute.	"date" | "false" | "location" | "page" | "step" | "time" | "true" | undefined	undefined
_ariaDescription	_aria-description	Defines the value for the aria-description attribute.	string | undefined	undefined
_ariaExpanded	_aria-expanded	Defines whether the interactive element of the component expanded something. (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded)	boolean | undefined	undefined
_disabled	_disabled	Makes the element not focusable and ignore all events.	boolean | undefined	false
_download	_download	Tells the browser that the link contains a file. Optionally sets the filename.	string | undefined	undefined
_hideLabel	_hide-label	Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it.	boolean | undefined	false
_href (required)	_href	Sets the target URI of the link or citation source.	string	undefined
_icons	_icons	Defines the icon classnames (e.g. _icons="fa-solid fa-user").	KoliBriHorizontalIcons & KoliBriVerticalIcons | string | undefined	undefined
_inline	_inline	Defines whether the component is displayed as a standalone block or inline without enforcing a minimum size of 44px.	boolean | undefined	true
_label	_label	Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to false to enable the expert slot.	string | undefined	undefined
_on	--	Defines the callback functions for links.	undefined | { onClick?: EventValueOrEventCallback<Event, string> | undefined; }	undefined
_role	_role	[DEPRECATED] We prefer the semantic role of the HTML element and do not allow for customization. We will remove this prop in the future. Defines the role of the components primary element.	"tab" | "treeitem" | undefined	undefined
_shortKey	_short-key	Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud.	string | undefined	undefined
_target	_target	Defines where to open the link.	string | undefined	undefined
_tooltipAlign	_tooltip-align	Defines where to show the Tooltip preferably: top, right, bottom or left.	"bottom" | "left" | "right" | "top" | undefined	'right'
_variant	_variant	Defines which variant should be used for presentation.	string | undefined	undefined

Methods

focus

focus() => Promise<void>

Sets focus on the internal element.

Returns

Type: Promise<void>

---