## Anatomy
The Link consists of two primary elements that work together to navigate users to another webpage, document, or section.
1. Text label
2. Open in new / external icon
## Options
The Link supports multiple appearances and external link configurations to accommodate various navigation scenarios.
| Appearance | When to use |
| ---------- | --------------------------------------------------------------------------- |
| Primary | For prominent, important links on the page. |
| Secondary | For inline text that does not need a lot of prominence. |
| Ghost | For standalone situations where a user can clearly understand it is a link. |
### With open in new Icon
When denoting that a link will open in a new tab, or when the link opens an external site, use the "open in new" icon, regardless of which appearance the link uses.
### Link Button
```tsx lines theme={null}
import { LinkButton, Flex } from "@servicetitan/anvil2";
function App() {
return (
Primary Link ButtonSecondary Link ButtonQuiet Link Button
);
}
export default App;
```
The **Link Button** is a specialized Button component styled to look like a simple text link. It provides the visual appearance of a link with the correct HTML semantics of a button, making it ideal for actions that do not navigate to a new page.
The [**Button Link**](/docs/web/components/button/design#button-link) is its reverse: a Button component that uses an anchor tag under the hood. Use it when an action involves navigation but you need a button's visual style.
## Behavior
The Link responds to user interaction with distinct visual states for different appearances.
### Visual States
#### Primary link
#### Secondary link
#### Ghost link
## Usage Guidelines
Use the Link when navigating users to another webpage, document, or section.
### When to Use
Links are typically used in navigation to new pages, new sites, moving to another element on the same page, emails, and phone numbers.
The Link component in the design system is limited in scope to being a standalone component. Components that have similar navigational behaviors, such as a side nav, tabs, or footer links do not use this Link component, either under the hood or visually.
### Alternatives
#### Link vs Button
In general, Buttons are used to denote an action, while a Link is used to denote navigation. This distinction in practice is sometimes blurry.
##### When navigating
In general, Links are the preferred choice for navigating. Use a Button in these scenarios:
* Use a Button when emphasis is needed. Sometimes a page's call to action is navigating somewhere else.
* Use a Button when navigation is mixed with actions.
##### With Actions
In general, Buttons are the preferred choice for actions. Use a Link when the action priority is low and space is tight.
##### With triggering overlays
Treat triggering an overlay UI like navigation.
### How to Use
#### External links
When a link goes to a site outside of the current domain, it should utilize the external icon, and also open in a new tab. This can be used with all link styles.
#### Underline vs no underline links
The underline variant of links is used when the link is part of a sentence or paragraph. When a link is a standalone element, omit the underline.
**Do**
**Don't**
**Do**
#### Primary vs Secondary styling
Use the primary link style when attention should be called upon itself. Use the secondary link when there are many links on the page, or when less emphasis should be placed on the links. Use caution when mixing both styles in one area, and don't use both in the same body of text.
**Do**
**Do**
**Don't**
## Content
Content within the Link should clearly communicate the destination and provide enough context for users to understand what to expect.
### Standalone links
Standalone links are written similarly to calls to action: They are not full sentences, have no punctuation except question marks, and use short action-oriented phrases.
Users typically see links as optional or supplemental content because they often appear at the end of a sentence or paragraph.
Links should never use "click here" or "here" as link text.
**Do**
**Don't**
### Links in sentences
The link should only include text that refers directly to the destination. Include enough context about the destination in the link text to allow the user to understand the value and know what to expect when they click.
Links in sentences are part of a paragraph. Include enough context in the link text to communicate the value and expectation of the landing experience.
**Do**
**Don't**
## Keyboard Interaction
Users can navigate the Link using standard keyboard controls.
| Key | Interaction |
| ----- | ---------------------------------------------------- |
| Enter | Engages the link and moves focus to the link target. |
### Accessibility
#### Annotate generic links
It is generally preferable the link does not use generic labels. If it does, an annotation for the link should be made in handoffs, either to a heading if one is available or as a custom label if there is not one.
#### Annotate a generic link using a headline
When a link is generic and a headline (or table column) is available, associate it with the heading. In development, the link is given an aria-labelledby. [Refer to W3C's guidelines on how to implement this](https://www.w3.org/WAI/WCAG21/Techniques/aria/ARIA7).
#### Annotate a generic link using a custom label
When a link is generic and has no label available, annotate a custom label for the link for screenreaders. In development, the link is given an aria-label. [Refer to W3C's guidelines on how to implement this](https://www.w3.org/WAI/WCAG21/Techniques/aria/ARIA8).
For more guidance on link labels and context association, see [link accessibility best practices](/docs/accessibility/labels-and-ctas#buttons-and-links).
