Links take users to another place, and usually appear within or directly following a sentence.
Use for text links inside a paragraph or for standalone text. Default links open in the same browser tab.
<script lang="ts" setup>
import { Link } from '@returnless/focus-ui';
</script>
<template>
<Link href="my-page">A link</Link>
</template><script lang="ts" setup>
import { Link } from '@returnless/focus-ui';
</script>
<template>
<Link href="my-page" external>A link</Link>
</template>Links are used primarily for navigation, and usually appear within or directly following a sentence.
Buttons are used primarily for actions, such as "Add", "Close", "Cancel", or "Save". The HTML that renders for the Button and Link components carriers meaning. Using these components intentionally and consistently results in:
Use default links whenever possible to avoid disorienting users and causing accessibility problems by opening a new tab.
External links should be used when users are:
Avoid using the external icon, as it can add unnecessary visual load inside a sentence or when accompanied by other content. Instead, add clarity to external links through clear link text and predictable placement of the link in a user's workflow.
Edge cases: External icons should not be used to indicate a new tab or window is being opened. However, they may be used sparingly in features where symbols help users scan and pick from a list of several kinds of navigation options.
Links need to be clear and predictable. Users should be able to anticipate what will happen when they select a link. Never mislead someone by mislabeling a link.
Links should never use "click here" or "here" as link text.
Links in full sentences shouldn't link the entire sentence, only the text that describes where users go when they select a link.
It's better for internationalization to have only single terms or small parts of phrases linked. Linking a full phrase is problematic because the word order might change, which would break the link into two parts.
Links that aren't in full sentences should use the {verb + noun} pattern and not be punctuated, except question marks.
When linking out to documentation from help text in the admin, link the relevant keywords. In general, don't add another sentence starting with "Learn more...", because it's repetitive and takes up unnecessary space.
Only add a "Learn more..." sentence if the help text addresses more than one concept, each of which could be linked to their own help doc. In that situation, pick the most appropriate link and contextualize it with "Learn more...".
Use the href prop to give the link component a valid href value. This allows the element to be identified as a link to assistive technologies and gives it default keyboard support.
The Link component is underlined to give interactive elements a shape. This allows links to not rely on color from being the only way users can tell if an element is interactive.
Users generally expect links to navigate, and not to submit data or take action. If you need a component that doesn't have a URL associated with it, then use the button component instead.
Give text links text that clearly describes their purpose.
The accessibilityLabel prop adds an aria-label attribute to the link, which can be accessed by assistive technologies like screen readers. Typically, this label text replaces the visual text on the link for users who use assistive technology.
To provide consistence and clarity:
Links use browser defaults for keyboard interaction.