Link

v0.4.4

Ready for Production

Catalyst Link wraps the standard HTML <a> element with built-in design tokens, CVA variants for underline and wrap control, and a disabled state — giving you a production-ready link with zero configuration.

Installation

npm install @pmi/catalyst-link

import { Link } from '@pmi/catalyst-link';

Variants

Underline Options

Controls when the underline decoration appears. Four values are available:

• auto — underline on hover (default). Clean at rest.
• always — permanently underlined. Best for body text where link affordance must be clear.
• hover — underline on hover only, identical to auto in most contexts.
• none — no underline. Use when context or styling already communicates interactivity.

Disabled

Sizes

Common Patterns

Truncated Text

Wrap Options

API Reference

Accessibility

Link is designed to meet WCAG 2.2 AA standards.

Keyboard Interactions

Disabled links have no href, so they are skipped by Tab by default and cannot be activated. A tabIndex={0} passed to a disabled link keeps it in sequential focus navigation, so avoid it unless the link must stay focusable.

ARIA attributes

• Uses the native <a> element, providing built-in link semantics for assistive technologies.
• When disabled is set, href is removed and pointer-events-none is applied. Because HTML does not provide a native disabled state for links, consider rendering non-interactive text instead when navigation is unavailable.
• For external links, always pair target="_blank" with rel="noopener noreferrer" to prevent reverse tabnapping and avoid leaking the opener reference.
• Use asChild with <NextLink> or React Router's <Link> to preserve native link semantics while enabling client-side navigation.

Additional Accessibility Guidance

Contrast and Appearance

• Default text colors (pmi-off-black-800 / white) meet the 4.5:1 minimum. Verify contrast when applying custom className overrides.
• Links should not be identified by color alone. Ensure non-color visual cues such as underlines, font styling, or other indicators distinguish links from surrounding text.
• Enabled links show an inset focus-visible ring and border by default (pmi-off-black-800 in light mode, white in dark mode). Keep a visible focus indicator when overriding styles.
• Use underline values consistently across your site so links are predictably identified by visual style.

Link Purpose and Icon - only links

• Provide descriptive link text; avoid generic labels like "Click Here", "Learn More", "View All".
• Require an accessible name through visible text, aria-label, or aria-labelledby.
• Decorative icons within links should be hidden from assistive technologies using aria-hidden="true" unless they convey meaningful information.

New Window Notification: (Best Practice)

• Inform users when a link opens a new tab or window, especially if the behavior is unexpected.

Choosing the Right Component

Use Link when you need to navigate to a URL. Reach for a different primitive when:

Related

• Button