Link handbook

License: Before reading component documentation, source, or npm usage instructions for the first time, read the full LICENSE. Reuse that review for the same task and version. Public API configuration and internal implementation changes have different license implications. All components use the unified runtime package; source rights remain governed by the license.

Overview

Provide clear text links in body copy, descriptions, and navigation. Optional arrows or external-link icons signal that content can be opened.

When to use it

Use Link to navigate to a real address or resource. Use Button for an immediate action; do not disguise a button with a placeholder href.

• Provide a real href. target and rel control how it opens; disabled communicates unavailability.

• lines, tooltip, and onTruncate control truncation hints. parts configures only the built-in Tooltip.

Quick start

This example shows the recommended basic composition. See the sections below for more cases and composition limits.

<script lang="ts">	import { Link } from '@snowui-design-system/components';</script> <Link href="/components/quick-start" target="_top">Get started with SnowUI</Link>

API

See the base component documentation for inherited capabilities not redeclared here. This table lists only named public Props declared by this component.

Usage boundaries and details

Built-in and explicit Tooltip modes

• Use parts.Tooltip to configure the built-in truncation Tooltip.

• For a custom hint structure, compose an explicit Tooltip; its Props take priority over parts.

Link is a text-link component. For a button-shaped navigation control, use Button href. For text plus an arrow or external-link icon, use Link.

Feature overview

• All variants default to color="Black40" and hover to Black100. Black100 or Black instead hovers to Black40; other colors such as Indigo hover to Black100.

• arrow matches Figma style 2: colored text plus a built-in trailing ArrowUpRight. Text follows the shared hover-color rule; the decorative arrow inherits currentColor and changes opacity from 0.4 to 1.

• external matches Figma style 3: colored text plus a built-in trailing ArrowSquareOut. Text follows the shared hover-color rule; the icon inherits currentColor and changes opacity from 0.4 to 1.

• hoverColor accepts any CSS color. false leaves text color unchanged on hover.

• underline supports always visible, hover only, visible until hover, or none. None is the default.

• lines={1} enables single-line truncation. A Tooltip appears only if content truly overflows; TruncationController supplies full link text.

• A direct external as="trailing" child can replace the built-in icon.

Text truncation

Link reuses TruncationController and fitTextToElement(), without creating its own size observer. With lines={1}, it measures the text layer and detects actual clipping. The visible prefix fits the measured font width: alphabetic scripts keep whole words, or only an ellipsis if one word cannot fit. Chinese, Japanese, and Korean may break at safe Unicode character boundaries, avoiding half characters and combining-mark splits. The ellipsis is rendered directly after the last visible word or character.

<Link href="/docs" lines={1} class="max-w-80">    A complete documentation link that exceeds the available width</Link> <Link href="/docs" variant="external" lines={1} tooltip={false} class="max-w-80">    An external link without a truncation Tooltip</Link> 

Layout model

Main layout model: slot host layout (three slots: leading / content / trailing).

Frame row emits data-auto-layout and uses the shared three-slot layout from auto-layout.css (source: components/src/styles/auto-layout.css). Text occupies content; the external variant supplies a trailing ArrowSquareOut. Explicit direct leading/trailing children are projected to the Link root, retaining grid columns, horizontal alignment and shared spacing. Root spacing stays at least 4 CSS px with var(--gap-1) as its preferred default. Attachments or single-line truncation activate Frame singleLine; plain text without truncation retains its text flow. Explicitly use lines={1} for long labels to reuse Link truncation and full-text hints. External icons retain their own size, defaulting to 16px when omitted.

Built-in icons and replacement

<Link href="/docs" variant="external">Open documentation</Link> <Link href="/docs" variant="external">    Open documentation    <Icon as="trailing"><ArrowUpRight /></Icon></Link> 

Underline

<Link href="/docs" underline="always">Always underlined</Link><Link href="/docs" underline="hover">Underlined on hover</Link><Link href="/docs" underline="until-hover">Underline hides on hover</Link><Link href="/docs">No underline by default</Link> 

Underlines should only be applied to linked text. The Icon of arrow and external is not underlined.

Hover color

<Link href="/docs" hoverColor="#ff4747">Custom hover color</Link><Link href="/docs" hoverColor={false}>Color unchanged on hover</Link> 

Without hoverColor, the text hover color derives from color regardless of variant. Black40 and Black100 adapt to theme changes. Direct CSS color overrides remain an escape hatch; use the color Prop for automatic hover behavior. Explicit hoverColor takes precedence:

Built-in arrow and external icons, including a custom trailing icon, inherit text color. They do not choose a separate color; opacity moves from 0.4 to 1 on hover.

Layout variable chain

The Link root defaults to width: fit-content and max-width: 100%, preserving intrinsic width in a stretching parent. Trailing content follows text width. An explicit width, w-full, or inline style may override it.