Link
A link takes the reader to another place. It matches the size and weight of the text around it and adds the link color and an underline.
Read our
<p>Read our <tk-link href="/privacy">privacy policy</tk-link> before you sign up.</p>
Anatomy
| Part | What it is |
|---|---|
tk-link |
the element; one Tab stop when it has href |
| default slot | the link text, required; it is the accessible name |
link part |
the native <a> inside |
A link has no size of its own. It takes its font from its surroundings, so it's Body Medium in a paragraph and larger in a heading. To change its size, style the text around it.
Variants
Underline
See the
<p>See the <tk-link href="/guide">setup guide</tk-link>.</p> <tk-link href="/pricing" underline="hover">Pricing</tk-link>
always(default): underlined at rest, so the link doesn't rely on color. Use it for every link in running text.hover: the underline shows on hover and keyboard focus. Use it only where it's already clear that it's a link, such as a nav row. Never in running text.
Color
Questions?
<p>Questions? <tk-link href="/help" color="inherit">Visit the help center</tk-link>.</p>
accent(default): the link color, distinct from body text.inherit: the color of the surrounding text; keep the underline.inverse: for a link on an inverse (dark) surface. Set the surface to the dark theme so the focus ring matches.
Don't combine color="inherit" with underline="hover": the link looks exactly like the
text around it. The component warns in the console.
Quiet
<nav aria-label="Account"> <tk-link href="/profile" treatment="quiet">Profile</tk-link> <tk-link href="/billing" treatment="quiet">Billing</tk-link> </nav>
treatment="quiet" is a muted link with no underline at rest. On hover and focus it gets
darker and shows the underline. It replaces color and underline, which then have no
effect. Use it only in navigation rows and trails, never in running text.
States
<tk-link href="/reports">Reports</tk-link> <tk-link aria-current="page">Current page</tk-link>
Hover, press, and focus need no props. Hover shows the underline and, for accent, a darker
color. Keyboard focus shows a ring.
- No
href: the link can't be focused or followed. There is nodisabled; leave outhrefinstead. aria-current="page": marks the link to the page the reader is on. The component passes it to the inner<a>.- Visited links look the same as unvisited ones.
External links
<tk-link href="https://example.com/report" target="_blank" external>Annual report (opens in a new tab)</tk-link>
target="_blank"opens a new tab and addsrel="noopener noreferrer"for you, together with anyrelyou set.externaladds a trailing external-link icon. It scales and colors with the text and is hidden from screen readers.- Say "opens in a new tab" in the text when that matters; the icon is silent.
When to use
- Use a link to go somewhere: a page, a route, an
#anchor, amailto:address, or a file. - Use a
Button to do something in place, such as save, open a dialog, or delete, even when it should look quiet. - Use
Breadcrumb orNavigation menu for a trail or a nav bar; they use links inside.
Content
- Name the destination: "privacy policy", "billing settings".
- Make it make sense out of context. Screen reader users often list links on their own.
- Avoid "click here" and "read more" without saying what.
- Keep it short: link the words that name the place, not the whole sentence.
Do / Don't
| ✅ Do | ❌ Don't |
|---|---|
| Use a link to go to another page | Make a link run an action |
| Keep links in text underlined | Use underline="hover" in a paragraph |
| Write "billing settings" | Write "click here" |
Leave out href when the link can't be followed |
Add a disabled attribute |
| Say "opens in a new tab" in the text | Open a new tab without warning |
| Style the surrounding text to resize a link | Expect a size attribute on the link |
Related
Button : for actions.Text : the text a link sits in.Breadcrumb : a trail of quiet links.Navigation menu : a nav bar built on links.Prose : plain<a>elements in Prose get the same look.
API
Attributes
| Attribute | Type | Default | What it does |
|---|---|---|---|
href |
string | none | the destination; leave it out for a link that can't be followed |
target |
string | none | the anchor target; _blank adds rel="noopener noreferrer" |
rel |
string | none | extra rel values |
underline |
always | hover |
always |
when the underline shows |
color |
accent | inherit | inverse |
accent |
the link color |
treatment |
standard | quiet |
standard |
quiet for navigation rows; replaces color and underline |
external |
boolean | false |
shows the external-link icon |
aria-current |
string | none | passed to the inner <a>; use page for the current page |
Slots
| Slot | Content |
|---|---|
| default | the link text, required; long text wraps with its underline |
Events
No custom events. Listen for click; Enter follows the link.
CSS
::part(link): the native<a>.
Tokens
| Link | Rest | Hover and press | Focus ring |
|---|---|---|---|
accent |
text/accent |
text/accent/hover |
border/accent/focus |
inherit |
the surrounding color | text/accent/hover |
border/accent/focus |
inverse |
text/inverse |
text/accent/hover |
border/inverse |
quiet |
text/secondary |
text/default |
border/accent/focus |
Values per theme:
Accessibility
Built in:
- A native
<a>: Tab reaches it when it hashref, Enter follows it, and the browser's open-in-new-tab and context menu work. - Underlined by default, so a link doesn't depend on color.
- A focus ring for keyboard users that is never hidden; the underline shows on focus too.
aria-currentreaches the inner<a>.- The external icon is hidden; the text names the link.
Your part:
- Write link text that names the destination.
- Keep links in running text underlined.
- Say in the text when a link opens a new tab.
- Use a link to navigate and a button to act.
| Key | Action |
|---|---|
Tab |
moves focus to the link (only when it has href) |
Enter |
follows the link |
Contrast limits
hoverunderline andquiet: at rest these links are told apart by color or position only. Use them where the context already says "link".inheritandinverseon hover: the text turnstext/accent/hover, which may be hard to read on a dark surface.