Link

A styled anchor for inline and standalone text navigation. Supports external links, underline variants, tooltips, and custom link components for router integration. Use it for navigating between pages or to external URLs.

Installation

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

Requires React 19+, base CSS and a Theme provider. See Setup.

Link

Usage guidance

Write descriptive, concise link text that clearly communicates the destination.
Set isStandalone when the link appears outside of inline text, so it receives proper base font sizing.
Only set label when the link content is not descriptive text (e.g. an icon-only link). For text links, the visible text is already the accessible name; adding label overrides it for screen readers, which is harmful.
Avoid: Use Link for actions that do not navigate; use a Button instead.
Avoid: Use generic text like "click here" or "read more"; describe the destination.
Avoid: Set label on text links; aria-label prevents assistive technology from reading the actual link content.

Theming API

{
  "targets": [
    {
      "className": "astryx-link",
      "visualProps": [
        "color"
      ]
    }
  ]
}

Link

Styled anchor link with variants, external link support, and polymorphic rendering.

Prop	Type	Default	Description
as	LinkComponentType		Custom component to render instead of <a>
label	string		Accessible label (aria-label). Only use when children are not self-descriptive (e.g. icon-only links). Omit for text links; the link text is the accessible name.
href	string		Link destination URL. Astryx-owned links and clickable surfaces block javascript:, vbscript:, and data:text/html after control-character removal, outer-whitespace trimming, and case-insensitive scheme inspection. The same rule covers native anchors, custom routers, Markdown links, and every activation method. Relative paths, fragments, protocol-relative URLs, HTTP(S), mailto, tel, safe custom schemes, and accepted downloads keep their existing behavior. A rejected destination renders inertly without invoking a custom router. There is no bypass prop; exceptional behavior requires caller-owned custom rendering outside this guarantee. Images and other resource URLs have separate policies.
hasUnderline	boolean	false	Always show underline
isDisabled	boolean	false	Disables the link
isExternalLink	boolean	false	Opens in new tab with external icon and safe rel tokens
newTabLabel	string	'(opens in new tab)'	Screen-reader text announcing that an external link opens in a new tab. Override for localization.
target	string		Where to open linked document. target="_blank" automatically adds noopener noreferrer.
rel	string		Link relationship tokens. noopener noreferrer are merged automatically for target="_blank".
download	string \| boolean		Causes the browser to download the linked URL. A string specifies the suggested filename.
referrerPolicy	HTMLAttributeReferrerPolicy		Referrer policy for the link.
onClick	MouseEventHandler		Click event handler
tooltip	string		Tooltip text displayed on hover
isStandalone	boolean	false	Applies base font sizing
size	'4xs' \| '3xs' \| '2xs' \| 'xsm' \| 'sm' \| 'base' \| 'lg' \| 'xl' \| '2xl' \| '3xl' \| '4xl'		Explicit font size override forwarded to Text.
weight	'normal' \| 'medium' \| 'semibold' \| 'bold'		Font weight override forwarded to Text.
color	'primary' \| 'secondary' \| 'disabled' \| 'placeholder' \| 'accent' \| 'inherit'	'accent'	Text color forwarded to Text.
display	'inline' \| 'block'	'inline'	Display type for Text.
maxLines	number	0	Maximum lines before truncation.
children *	ReactNode		Link content

Link Provider

Provider that sets the default link component for all Astryx link-rendering components in the subtree. Wrap your app root to replace native <a> elements with your framework router (Next.js Link, React Router Link, etc.).

Prop	Type	Default	Description
component *	LinkComponentType		Component to use for all link elements. It receives accepted `href` and `to` values under the shared navigation rule described on the Link `href` prop. Supported structured destinations, including their `protocol`, are checked without changing object identity. If either supplied destination is rejected, Astryx renders inert content without invoking this component; it does not pass undefined or fall back to the other destination.
children *	ReactNode		Subtree

Accessibility

Link text: Link text must have at least 4.5:1 contrast with the background behind it. For Pointer down, measure against the pressed overlay the link paints behind its text. — 4.5:1

Anatomy

Label: The visible text of the link.
Right icon: Icon placed after the label to indicate an action affordance.
Left icon: Icon placed before the label to represent meaning.

Link Provider

Wraps your app to replace the default <a> tag with a framework-specific link component (e.g. Next.js Link) for client-side routing across all Astryx components.

Prop	Type	Default	Description
component *	LinkComponentType		Link component to use for all link elements in the subtree (e.g. Next.js Link). It receives accepted `href` and `to` values under the shared navigation rule described on the Link `href` prop. Supported structured destinations, including their `protocol`, are checked without changing object identity. If either supplied destination is rejected, Astryx renders inert content without invoking this component; it does not pass undefined or fall back to the other destination.
children *	ReactNode		Content to render with the link provider.

Examples

Link: A standalone link.
Link — External Links: A vertical list of external links that open in a new tab with an indicator icon.
Link — Inline Text: A link embedded within a paragraph of body text.
Link Provider — Custom Link Component: Routes every Astryx link through a custom component that intercepts the click, the hook frameworks like Next.js use for client-side navigation. Click the link to see the custom handler fire instead of a full-page load.
Link — With Tooltips: Horizontal row of standalone links with descriptive hover tooltips.