HyLink

Usage examples on this page are written for Lit / plain HTML (<hy-link>). The same component ships as HyLink in @whitespaceux/harmony-react (native React 19), with typed wrappers for Angular, Solid, Svelte, and Vue. The API reference below applies to all frameworks.

A versatile link component that provides enhanced styling and functionality over standard anchor tags. Supports multiple visual variants, size options, disabled states, comprehensive accessibility features, form integration, and flexible content slots. Optimized for performance with hardware acceleration and includes full keyboard navigation, screen reader support, responsive design capabilities, high contrast mode support, reduced motion preferences, and print-friendly styling.

Features

• Multiple variants (default, emphasis, navigation) and sizes (small, medium, large)
• Conditional gap spacing - gaps only appear between prefix/suffix content for default and emphasis variants
• Enhanced accessibility with ARIA support, high contrast mode, reduced motion, and screen reader announcements
• Form integration with validation and comprehensive error handling
• Container queries for responsive behavior
• Dark mode and high contrast support with automatic color adjustments
• Performance optimized with hardware acceleration and CSS transforms
• Touch-friendly targets on mobile devices
• Print-friendly styles with URL display for external links

Examples

Basic usage

<hy-link href="/about" label="About Us"></hy-link>

Different sizes and variants

<hy-link href="/profile" variant="emphasis" size="large"> Large Emphasis Link </hy-link>
<hy-link href="/settings" size="small">Small Link</hy-link>

Navigation variant with bottom border indicator

<hy-link href="/home" variant="navigation">Home</hy-link>
<hy-link href="/about" variant="navigation" selected>About</hy-link>

With slots for icons (automatic gap spacing)

<hy-link href="/profile" variant="emphasis">
  <hy-icon name="user" slot="prefix"></hy-icon>
  User Profile
  <hy-icon name="arrow-right" slot="suffix"></hy-icon>
</hy-link>

Form submission with validation

External link with accessibility

<hy-link
  href="https://example.com"
  target="_blank"
  variant="emphasis"
  aria-label="Visit Example.com (opens in new window)"
>
  External Link
  <hy-icon name="external-link" slot="suffix"></hy-icon>
</hy-link>

Disabled and selected states

<hy-link href="/current" selected>Current Page</hy-link>
<hy-link href="/disabled" disabled>Disabled Link</hy-link>

API

Properties

Property	Attribute	Type	Default	Description
href	href	string	'#'	The URL to navigate to when clicked. Use '#' for form submission or button behavior.
target	target	'_blank' | '_parent' | '_self' | '_top'	—	Tells the browser where to open the link.
download	download	string | undefined	—	Tells the browser to download the linked file as this filename.
label	label	string	'Link'	The text content of the link. If slot content is provided, this will be ignored.
variant	variant	'default' | 'emphasis' | 'navigation'	'default'	The variant type of the link. - default: Standard link with underline decoration - emphasis: Link with colored underline for emphasis - navigation: Navigation-style link with bottom border indicator and padding
size	size	'small' | 'medium' | 'large'	'medium'	The size of the link. Affects font size, spacing, and touch targets.
disabled	disabled	—	—	Disables the link and prevents all interactions. Announces state changes to screen readers.
selected	selected	boolean	false	Marks the link as selected/active. Useful for navigation menus. Shows bottom border for navigation variant.
form	form	string | undefined	—	The form to submit when href="#". References a form element by ID. Triggers form-submit event.
formaction	formaction	string | undefined	—	The URL to submit the form data to when href="#". Overrides form's action attribute.
formmethod	formmethod	'get' | 'post'	—	The HTTP method to use when submitting the form when href="#". Overrides form's method attribute.
formenctype	formenctype	'application/x-www-form-urlencoded' | 'multipart/form-data' | 'text/plain'	—	The encoding type for form submission when href="#". Overrides form's enctype attribute.
formnovalidate	formnovalidate	boolean	false	Indicates that the form should not be validated when submitted via this link.
formtarget	formtarget	'_blank' | '_parent' | '_self' | '_top'	—	Specifies where to display the response after submitting the form. Overrides form's target attribute.
ariaLabel	aria-label	string | null	null	Custom ARIA label for enhanced accessibility. Automatically enhanced with contextual information.
ariaDescribedby	aria-describedby	string | null	null	ID of element that describes this link for screen readers.
ariaExpanded	aria-expanded	'true' | 'false'	null	Indicates if link controls an expandable element (true/false/null for none).

Events

Event	Detail	Description
focus	—	Fired when the link receives focus
blur	—	Fired when the link loses focus
form-submit	—	Fired when form submission is triggered (cancelable)
validation-error	—	Fired when form validation fails
form-error	—	Fired when form submission encounters an error

Slots

Slot	Description
default	The default slot for link text content (alternative to label property)
prefix	Content to show before the link text (icons, badges, etc.). Creates automatic gap spacing for default and emphasis variants.
suffix	Content to show after the link text (icons, arrows, etc.). Creates automatic gap spacing for default and emphasis variants.

CSS Parts

Part	Description
base	The link's base anchor element
label	The link's text content wrapper
prefix	The prefix slot wrapper
suffix	The suffix slot wrapper Click gating: Native click events bubble normally. When disabled, clicks are stopped (stopPropagation + preventDefault) on the host so external listeners never see them.

CSS Custom Properties

Property	Description
--hy-link-text-transform	Text transform for link text
--hy-link-underline-offset	Text underline offset
--hy-link-hover-duration	Transition duration for hover and focus state feedback
--hy-link-hover-easing	Transition easing for hover and focus state feedback

Methods

click()

Simulates a click on the link. Respects disabled state.

const link = document.querySelector('hy-link');
if (!link.disabled) {
  link.click(); // Programmatically trigger the link
}

focus()

Sets focus on the link. Automatically skipped if disabled.

Parameters:

• options - Optional focus options (preventScroll, etc.)

const link = document.querySelector('hy-link');
link.focus({ preventScroll: true });

blur()

Removes focus from the link.

const link = document.querySelector('hy-link');
link.blur();