> ## Documentation Index
> Fetch the complete documentation index at: https://anvil.servicetitan.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Link - Web
> Links are clickable elements that navigate users to another webpage, document, or section.
> [!NOTE]
>
> For development, import `Link` from
> `@servicetitan/anvil2`. For design, find it in the
> [Anvil2 file](https://www.figma.com/design/xaNQsvRKczoxu7pj0M6QT8/Anvil2-v3?node-id=16-5949).
## 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
link-button
[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/link-button?file=src/App.tsx)
```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**](https://anvil.servicetitan.com/docs/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
| Standard | Requirement |
| - | - |
| DoNavigate to pages, sections, or contacts | Links are typically used in navigation to new pages, new sites, moving to another element on the same page, emails, and phone numbers. |
| DoUnderline links within sentences | Use the underline variant when the link is part of a sentence or paragraph; see [Underline vs no underline links](#underline-vs-no-underline-links). |
| DoPrimary style for emphasis | Use the primary link style when attention should be called upon itself; see [Primary vs Secondary styling](#primary-vs-secondary-styling). |
| DoSecondary style for many or lower-emphasis links | Use the secondary link style when there are many links on the page, or when less emphasis should be placed on them; see [Primary vs Secondary styling](#primary-vs-secondary-styling). |
| Don'tPower similar navigational components | The Link component 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. |
| Don'tUnderline standalone links | Omit the underline when a link is a standalone element; see [Underline vs no underline links](#underline-vs-no-underline-links). |
| Don'tMixing primary and secondary styles | Don't use both primary and secondary link styles in the same body of text; see [Primary vs Secondary styling](#primary-vs-secondary-styling). |
### When to Use
Use the Link Button when:
* **Actions that don't navigate** – An action does not navigate to a new page but needs the visual appearance of a text link.
* **Button semantics with link styling** – The control must be an HTML button while looking like a Link.
### When not to use
Avoid using the Link Button for:
* **Navigating to another page** – Use the Link for navigation instead.
* **Navigation that needs a button's style** – Use the [Button Link](https://anvil.servicetitan.com/docs/components/button/web.md#button-link) instead.
* **Most actions** – Buttons are the preferred choice for actions; use a [Button](https://anvil.servicetitan.com/docs/components/button/web.md) instead.
### 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.
> [!TIP]
>
> **Do**
> [!CAUTION]
>
> **Don't**
> [!TIP]
>
> **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.
> [!TIP]
>
> **Do**
> [!TIP]
>
> **Do**
> [!CAUTION]
>
> **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.
> [!TIP]
>
> **Do**
> [!CAUTION]
>
> **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.
> [!TIP]
>
> **Do**
> [!CAUTION]
>
> **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](https://anvil.servicetitan.com/docs/accessibility/labels-and-ctas.md#buttons-and-links).
## Code
**Implementation**
link-playground
[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/link-playground?file=src/App.tsx)
```tsx lines expandable theme={null}
import { Link } from "@servicetitan/anvil2";
function App() {
return (
Link Example
);
}
export default App;
```
## Common Examples
```tsx theme={null}
import { Link } from "@servicetitan/anvil2";
function ExampleComponent() {
return (
Link
);
}
```
### Link variations
The `Link` component is used in place of an HTML `a` anchor tag to navigate the user to a different page or website.
link-props
[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/link-props?file=src/App.tsx)
```tsx lines expandable theme={null}
import { Link, Flex } from "@servicetitan/anvil2";
function App() {
return (
Primary Link
External Link
Secondary Link
Ghost Link
);
}
export default App;
```
### Button styled as a link
The `LinkButton` component is used to create an HTML `button` element that is styled to look like a link. It accepts the same props as the `Link` component, but extends the HTML `button` element props rather than HTML `a` props.
link-button
[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/link-button?file=src/App.tsx)
```tsx lines expandable theme={null}
import { LinkButton, Flex } from "@servicetitan/anvil2";
function App() {
return (
Primary Link ButtonSecondary Link ButtonQuiet Link Button
);
}
export default App;
```
## React Accessibility
The `Link` component is designed to have many accessibility features by default. Some considerations remain for the developer:
* The context for a link should be clear from the link text. In extreme cases, an `aria-label` should be used to give screen readers additional context.
* The link text should be concise. Only include what is necessary to understand the context. Remember that screen readers use this text to give context.
* Be careful when linking to full URLs. When linking to a URL, consider users with screen readers who need to hear it announced.
For more guidance on link labels and context association, see [link accessibility best practices](https://anvil.servicetitan.com/docs/accessibility/labels-and-ctas.md#buttons-and-links).
**Link Props**
```tsx theme={null}
Link text
```
## `Link` Props
In addition to the props listed below, the `Link` component also accepts any valid HTML `` props, such as `href` and `target`.
**appearance** `"primary" | "secondary"` (default: primary)
**ghost** `boolean`
Whether the link should have a quieter, less prominent appearance.
\[!NOTE] `ghost` can only be `true` when `appearance="primary"`.
**LinkButton Props**
```tsx theme={null}
console.log("Clicked")}
>
Link button text
```
## `LinkButton` Props
In addition to the props listed below, the `LinkButton` component also accepts any valid HTML `