@atlaskit/primitives/constellation/anchor/usage.mdx

Primitives are token-backed low-level building blocks.

---
title: Anchor
description: An anchor is a primitive for building custom links.
order: 2
---

import anchor1Do from './images/anchor-01a-do.png';
import anchor1Dont from './images/anchor-01b-dont.png';
import anchor2Do from './images/anchor-02a-do.png';
import anchor2Dont from './images/anchor-02b-dont.png';

## Usage

Use an anchor to make custom links. Anchors help users navigate to another page or sections of a
page. They can also download files or provide contact information such as phone numbers or email
addresses.

Anchor is based on the HTML `<a>` tag, with Atlassian focus styles and event tracking built-in. You
can customize the anchor's appearance using our styling APIs.

For example, an anchor could be used to make
[a link card](/components/primitives/anchor/examples#advanced-styling) with a larger clickable area
than a typical [link](/components/link/examples).

### Use links, link buttons, or other existing components where possible

Anchor is meant for custom elements and styles that aren't possible using other components. For
standard links or buttons that navigate users to a new location, use
[link](/components/link/examples) or [link button](/components/button/link-button/examples).

Using [existing components](/components) wherever possible makes Atlassian's UI more visually
consistent, and these components are faster to use for most basic use cases.

## Accessibility

### Differentiate anchors from regular text

Anchors are underlined by default. This helps differentiate links from regular text, which is an
accessibility requirement. Using color alone to differentiate links isn't accessible, especially if
links are surrounded by other text.

<DoDont
	type="do"
	image={{
		url: anchor1Do,
		alt: 'A link surrounded by regular text. The link provides color and an underline to differentiate the link from regular text.',
	}}
>
	Use both underlines and color for links surrounded by regular text.
</DoDont>

<DoDont
	type="dont"
	image={{
		url: anchor1Dont,
		alt: "A link surrounded by regular text. The link provides only color but no underline to differentiate the link from regular text, however it's insufficient.",
	}}
>
	Only use color to differentiate links from regular text.
</DoDont>

Only remove underlines and omit other style affordances such as color if the context surrounding the
link makes it clear that it's interactive, such as in navigation or a card layout.

<DoDont
	type="do"
	image={{
		url: anchor2Do,
		alt: 'Links in a navigation section. The links use a subtle text color and no underline, which is appropriate because the surrounding context makes it clear that they are links.',
	}}
>
	Omit underlines and color when surrounding context makes it clear it's a link.
</DoDont>

<DoDont
	type="dont"
	image={{
		url: anchor2Dont,
		alt: 'Links in a navigation section. The links use a bright text color and underline, which is not required because the surrounding context makes it clear that they are links.',
	}}
>
	Use underlines and color when surrounding context already makes it clear it's a link.
</DoDont>

Also, don't underline text that isn't a link. This makes the text look clickable because it looks a
link.

For more information see
['Understanding Use of Color (Level A)'](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html)
and
['Failure of Success Criterion 1.4.1 due to creating links that are not visually evident without color vision'](https://www.w3.org/WAI/WCAG22/Techniques/failures/F73).

<Snippet name="links-dont-confuse-with-buttons" variables={{ componentName: 'anchor' }} />

Don't use anchor to make custom actions rather than navigation elements. To build a custom button,
use the [pressable primitive](/components/primitives/pressable/examples) instead.

<Snippet name="links-descriptive-text" />

<Snippet name="links-open-new-window" variables={{ componentName: 'anchor' }} />

<Snippet name="links-minimum-size" />

If anchor is used for non-textual links, ensure the clickable area is at least 24 by 24 pixels for
accessibility. For more information see
[Target Size (Minimum) (Level AA)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html).

<Snippet name="links-content-guidelines" />

## Related

- Use existing components such as [link](/components/link/examples) or
  [link button](/components/button/link-button/examples) wherever possible.
- Use [pressable primitive for custom buttons](/components/primitives/button/usage).