packages/react-components/react-link/library/docs/SPEC.md
GitHub Epic issue - Link Convergence #16572
The Link component references data that a user can follow by clicking or tapping it.
The Open UI Link Research page (currently in PR: https://github.com/WICG/open-ui/pull/253), shows how the Link component is used in UI platforms across the web. The consensus across libraries seems to center around a simple interface with few variants that mostly attempt to support the functionality of the <a> HTML tag.
The existing components are:
Link componentBasic examples:
<Link>This is a link</Link>
<Link href="https://www.bing.com">This is a link</Link>
<Link href="https://www.bing.com" disabled>This is a link</Link>
<Link href="https://www.bing.com" target="_blank">This is a link</Link>
A Link has two decoration variants depending on where it's used.
By default, the Link should be limited to homogeneous surface areas where everything is clickable in the space and should appear as lacking an underline.
A second inline variant is provided for scenarios where body text is going to be used alongside a Link. This variant adds an underline to add a separate visual distinction in addition to color for contrast purposes.
A Link renders as different HTML tags depending on the whether a value has been passed for the href property or not. If a value has been passed to the href property, then the Link renders as an <a> HTML tag. Conversely, if the href property is left undefined the Link renders as a <button> HTML tag.
The Link can also be custom rendered as something entirely different by replacing the root slot with the preferred element to be rendered via the as prop.
root - The outer container representing the Link itself that wraps everything passed via the children prop.See API at Link.types.ts.
For Links rendering as <a>:
<a class="root" href={href}>
{children}
</a>
For Links rendering as anything other than <a> (the example below uses <button>):
<button class="root" role="link">
{children}
</button>
See MIGRATION.md.
The following section describes the different states in which a Link can be throughout the course of interaction with it.
An enabled Link communicates interaction by having styling that invites the user to click/tap on it to navigate through content.
A disabled Link is non-interactive, disallowing the user to click/tap on it to navigate through content.
A hovered Link changes styling to communicate that the user has placed a cursor above it.
A focused Link changes styling to communicate that the user has placed keyboard focus on it. This styling is usually the same to the one in the hovered state plus extra styling on the outline to indicate keyboard focus has been placed on the component.
A pressed Link changes styling to communicate that the user is currently pressing it.
A visited Link changes styling to communicate that the user has already interacted with it so its referenced content has already been accessed in the past.
The following is a set of keys that interact with the Link component:
| Key | Description |
|---|---|
Enter | Executes the Link and moves focus to its target. |
Shift + F10 (Optional) | Opens a context menu for the Link. |
mouseenter: Should immediately change the styling of the Link so that it appears to be hovered.mouseleave: Should immediately remove the hovered styling of the Link.mouseup: If triggered while cursor is still inside of the Link's boundaries, then it should execute the Link and move focus to its target.The same behavior as above translated for touch events. This means that there is no equivalent for mouseenter and mouseleave, which makes it so that the hovered state cannot be accessed.
a element unless something else has been specified for the root slot, in which case role="link" should be added to it.a native element.