Link

Usage

• Use Link for navigation — going to a new page, downloading a file, or linking to an email address or phone number.
• Use Link as an inline button (onClick without href) when an action needs link styling. Reserve this pattern for actions within inline text.
• Prefer Button for standalone calls-to-action and on-page actions such as opening a modal or drawer or submitting a form.
• Never treat Links and Buttons as interchangeable — links navigate via URLs, buttons perform actions on the current page.
• Mark links pointing outside the application with isExternal — they open in a new tab with safe HTML attributes (target="_blank" rel="noopener noreferrer") already applied.
• Wrap only the text that gives the best context on where the link goes or what it does — never wrap entire sentences or paragraphs.

Types

• Regular link — provide href to navigate to a page, file, or external resource.
• Button link — provide onClick without href to trigger an action inline while keeping link styling. The component renders a <button> element automatically.

Variants

• variant="primary" — use for standalone links. Uses text accent colors, no underline by default.
• variant="secondary" — use for links inside body text. Underlined by default to distinguish them from surrounding text.

Appearance

• Add an underline to a primary link with isUnderlined when extra emphasis is needed — the font weight updates to match surrounding body text.
• Remove the underline from a secondary link with isUnderlined={false} when the link is already visually distinct — the font weight updates to bold.
• Use icon to render a Pluma icon. Icons add visual context and never replace the label.
• Use iconSrc to supply a custom image icon when no Pluma icon fits the context. Custom icons follow the same rules as Pluma icons — same default size, same leading or trailing placement.
• Use iconPosition="leading" (default) to clarify the destination. Use iconPosition="trailing" for external links or to signal that a workflow continues.
• Pair external links with a trailing exit icon (icon="exit" iconPosition="trailing").
• Never use an icon whose meaning is unrelated to the link's purpose.
• Set icon size with iconSize — accepts fill, xxs, xs, sm (default), md, lg, xl.
• Override icon vertical alignment with iconAlignment — defaults to uppercase for leading icons and lowercase for trailing icons.
• Use iconLeading / iconTrailing when a link needs an icon on both sides at once. They render in addition to icon, never in place of it.
• Use elementBefore / elementAfter for leading or trailing content that isn't an icon. They pick up the same spacing the icons use, including when the link sits inside a paragraph.

Behaviors

• Base state — resting styles, applied when no other state prop is set.
• Loading state (isLoading) — overlays a spinner on the link content. The link acts as disabled while loading.
• Hover — the text color updates automatically to indicate interactivity. No prop required.
• Focus — the standard 2px light blue outline is applied automatically. No prop required.
• Disabled state (isDisabled) — blocks interaction and applies a muted text color.
• Danger state (isError) — applies critical color styling for a destructive action or error condition. Combines with isDisabled.
• Enable truncation with truncate — links do not truncate within smaller containers and viewports by default.

Content

• Use sentence case for link text.
• Write labels that accurately describe where the link goes or what action it performs.
• Write descriptive labels that make sense in isolation — never use "click here" or other generic phrases.
• Use a specific action verb or short verb phrase for action links (e.g. "Manage identities", not "Options").
• Embed inline links naturally into the sentence structure.
• Keep truncated links understandable — write descriptive labels that survive clipping.

Implementation Notes

• Link extends PlainLink and inherits href, isDisabled, isExternal, withSafeExternalAttributes, and replace.
• Auto-loading (autoLoading, default true) shows the spinner automatically when onClick returns a promise. Set autoLoading={false} to drive the spinner manually with isLoading.
• Set withSafeExternalAttributes={false} to turn off the automatic target="_blank" rel="noopener noreferrer" for other protocols such as mailto: or tel:.
• The element is polymorphic via as — it defaults to a and resolves to button when onClick is set, href is absent, and as is not given. Set as explicitly to override.
• truncate accepts true or the string 'true'. Truncation also drops inline icon alignment, so iconAlignment has no effect while truncation is on.
• iconSrc images always render with alt="" — they are decorative, so meaning must come from the link text or an aria-label.
• The design doc heading says "Danger" but the prop is isError — use isError in code.
• unsafe_isLegacy is deprecated and will be removed in the next major. Never set it; the component already renders in the target style.
• React: pass content as children; elementBefore / elementAfter take nodes. Ember: pass content via {{yield}} (default block); elementBefore / elementAfter take a component or the :elementBefore / :elementAfter named blocks.
• Ember invocation: <PlumaLink @href="#" @variant="primary">Label</PlumaLink>.