Link
pivot-link is a wrapper around the native <a> element. It exposes common anchor attributes as properties and supports light and dark surface variants along with typography size tokens via pivot-size.
Quick Start
<!-- Basic link -->
<pivot-link pivot-href="https://example.com">Visit Example</pivot-link>
<!-- Opens in a new tab — always pair with rel="noopener noreferrer" -->
<pivot-link
pivot-href="https://example.com"
pivot-target="_blank"
pivot-rel="noopener noreferrer"
>
Visit Example
</pivot-link>Size Variants
Two body text sizes are supported by the component’s CSS: "body-md" and "body-sm". Font size and line height are otherwise inherited from the surrounding text, so pivot-size only needs to be set explicitly when the link appears outside of a standard body text context.
<!-- Body medium -->
<pivot-link pivot-href="/page" pivot-size="body-md">Body MD link</pivot-link>
<!-- Body small -->
<pivot-link pivot-href="/page" pivot-size="body-sm">Body SM link</pivot-link>Dark Surface Variant
Use pivot-on-dark when the link sits directly on a dark background. This switches all link color tokens (default, hover, visited) to the on-dark set.
<div style="background: #1a1a1a; padding: 16px;">
<pivot-link pivot-href="/page" pivot-on-dark
>Link on dark background</pivot-link
>
</div>Inheriting dark context from pivot-text
When pivot-link is placed inside a pivot-text[pivot-on-dark] element, it automatically inherits the dark color tokens via CSS custom properties (--__link-color, --__link-color-hover, --__link-color-visited) that pivot-text sets on itself when pivot-on-dark is present. pivot-on-dark does not need to be set on the link itself in that case.
<!-- ✅ pivot-on-dark only on the parent — link colors are inherited automatically -->
<pivot-text pivot-on-dark>
Read our
<pivot-link pivot-href="/page" pivot-inline>getting started guide</pivot-link>
to learn more.
</pivot-text>When pivot-link sits on a dark background but outside of pivot-text, set pivot-on-dark directly on the link — the custom properties above have no other source, so without either a pivot-text[pivot-on-dark] ancestor or the attribute on the link itself, the link falls back to its light-surface colors:
<!-- ✅ pivot-on-dark set directly when not inside pivot-text[pivot-on-dark] -->
<p>
Read our
<pivot-link pivot-href="/page" pivot-inline pivot-on-dark
>getting started guide</pivot-link
>
to learn more.
</p>Inline Layout
By default, pivot-link renders as display: flow-root, creating a block-level container. Add pivot-inline to render the host as display: unset when the link is embedded within a sentence or paragraph.
<p>
Learn more about our
<pivot-link pivot-href="/about" pivot-inline>design system</pivot-link>
on the documentation site.
</p>External Links
When linking to an external site or opening in a new tab, always set pivot-rel="noopener noreferrer" to prevent tab-napping and avoid leaking referrer information.
<pivot-link
pivot-href="https://example.com"
pivot-target="_blank"
pivot-rel="noopener noreferrer"
>
External site
</pivot-link>Download Links
Use pivot-download to trigger a file download. The value becomes the suggested filename.
<pivot-link pivot-href="/files/report.pdf" pivot-download="annual-report.pdf">
Download Annual Report
</pivot-link>Accessibility
pivot-link renders a native <a> element internally, so it carries full browser link semantics with no additional ARIA required in standard usage.
Link Purpose and Accessible Naming
Set pivot-aria-label when the visible link text is not descriptive on its own — for example, repeated “Read more” links on a page. Per WCAG 2.4.4 (Link Purpose, In Context) and 2.4.9 (Link Purpose, Link Only), a link’s purpose should be identifiable from its accessible name alone.
<!-- ❌ Ambiguous — screen readers will announce "Read more" with no context -->
<pivot-link pivot-href="/article-1">Read more</pivot-link>
<pivot-link pivot-href="/article-2">Read more</pivot-link>
<!-- ✅ Descriptive accessible name via pivot-aria-label -->
<pivot-link
pivot-href="/article-1"
pivot-aria-label="Read more about the FCS launch"
>Read more</pivot-link
>
<pivot-link
pivot-href="/article-2"
pivot-aria-label="Read more about the AGD update"
>Read more</pivot-link
>pivot-aria-label maps to aria-label on the inner <a>, which per WCAG 4.1.2 (Name, Role, Value) overrides the accessible name computed from the slotted text for assistive technology, while the visible slotted text is unchanged.
Screen Reader Behavior
Screen readers announce:
- The link’s accessible name (
aria-labelwhen set viapivot-aria-label, otherwise the slotted text) - The element role: “link”
- Visited state, when applicable
The inner <a> element provides these semantics natively. No additional ARIA roles or attributes are needed for standard link usage.
Keyboard Navigation
Keyboard behavior is entirely native — pivot-link adds no key handlers of its own.
| Key | Action |
|---|---|
Tab |
Moves focus to the link |
Enter |
Activates the link and navigates |
This satisfies WCAG 2.1.1 (Keyboard) — all functionality is operable through the keyboard alone, with no custom focus trap or keyboard interception to work around.
Focus Management
pivot-link inherits shadowRootOptions with delegatesFocus: true from PivotBase. Focus on the host element is automatically forwarded to the inner <a>, so both programmatic .focus() and keyboard Tab navigation land on the native anchor, and the browser’s native focus ring is what’s visible — satisfying WCAG 2.4.7 (Focus Visible) without any custom styling.
Related Components
- Text — typographic body copy component. When
pivot-linkis slotted inside apivot-text[pivot-on-dark]element, it inherits dark-surface link colors automatically (see Inheriting dark context frompivot-textabove).
References
- MDN —
<a>: The Anchor element - WCAG 2.2 — 2.4.4 Link Purpose (In Context)
- WCAG 2.2 — 2.4.9 Link Purpose (Link Only)
- ARIA APG — Link Pattern
API Reference
Props
| Name | Type | Default | Description |
|---|---|---|---|
pivot-size |
string |
"body-md-regular" |
This will create an attribute: pivot-size="value" |
pivot-href |
string |
"" |
This will create an attribute: pivot-href="value" |
pivot-id |
string | undefined |
undefined |
This will create an attribute: pivot-id="value" |
pivot-on-dark |
boolean |
false |
Presence of attribute means true: <pivot-link pivot-on-dark>...</pivot-link> |
pivot-inline |
boolean |
false |
Presence of attribute means true: <pivot-link pivot-inline>...</pivot-link> |
pivot-target |
"_self" | "_blank" | "_parent" | "_top" | undefined |
undefined |
This will create an attribute: pivot-target="value" |
pivot-download |
string |
undefined |
This will create an attribute: pivot-download="filename.ext" |
pivot-hreflang |
string |
undefined |
This will create an attribute: pivot-hreflang="value" |
pivot-aria-label |
string |
undefined |
This will create an attribute: pivot-aria-label="value" |
pivot-rel |
"alternate" | "author" | "bookmark" | "external" | "help" | "license" | "next" | "nofollow" | "noreferrer" | "noopener" | "prev" | "search" | "tag" | undefined |
undefined |
This will create an attribute: pivot-rel="value" |
pivot-type |
string | undefined |
undefined |
This will create an attribute: pivot-type="media_type" |
Slots
| Name | Description |
|---|---|
default |
The link's text or content |
CSS Custom Properties
| Name | Description |
|---|---|
--__link-color |
Link text color (default state). Set by a `pivot-on-dark` ancestor (e.g. `pivot-text[pivot-on-dark]`) so the link inherits dark-surface coloring automatically. |
--__link-color-hover |
Link text color on hover. Set by a `pivot-on-dark` ancestor for automatic dark-surface inheritance. |
--__link-color-visited |
Link text color once visited. Set by a `pivot-on-dark` ancestor for automatic dark-surface inheritance. |
Default — body-md, light surface, block
<pivot-link pivot-href="#">Default link (body-md)</pivot-link>Size — body-sm, light surface, block
<pivot-link pivot-href="#" pivot-size="body-sm"
>Small link (body-sm)</pivot-link
>Inline — body-md, light surface, inline
<pivot-text>
This is body text with a
<pivot-link pivot-href="#" pivot-inline>body-md inline link</pivot-link>
embedded inside it.
</pivot-text>Inline — body-sm, light surface, inline
<pivot-text pivot-size="body-sm">
This is small body text with a
<pivot-link pivot-href="#" pivot-inline pivot-size="body-sm"
>body-sm inline link</pivot-link
>
embedded inside it.
</pivot-text>On Dark — body-md, dark surface, block
<pivot-link pivot-href="#" pivot-on-dark
>Default link on dark (body-md)</pivot-link
>On Dark — body-sm, dark surface, block
<pivot-link pivot-href="#" pivot-size="body-sm" pivot-on-dark
>Small link on dark (body-sm)</pivot-link
>On Dark + Inline — inherited from pivot-text (no pivot-on-dark on link)
<!-- pivot-link inherits dark context automatically from pivot-text[pivot-on-dark] -->
<pivot-text pivot-on-dark>
This is body text on a dark surface with a
<pivot-link pivot-href="#" pivot-inline>body-md inline link</pivot-link>
— no pivot-on-dark needed on the link.
</pivot-text>On Dark + Inline — pivot-on-dark set directly on link (outside pivot-text)
This is plain text on a dark surface with a
<!-- Use pivot-on-dark directly when pivot-link is not inside pivot-text[pivot-on-dark] -->
<p>
This is plain text on a dark surface with a
<pivot-link pivot-href="#" pivot-inline pivot-on-dark
>body-md inline link</pivot-link
>
using pivot-on-dark directly.
</p>On Dark + Inline — body-sm, dark surface, inline
<pivot-text pivot-size="body-sm" pivot-on-dark>
This is small body text on a dark surface with a
<pivot-link pivot-href="#" pivot-inline pivot-size="body-sm" pivot-on-dark
>body-sm inline link</pivot-link
>
embedded inside it.
</pivot-text>External — opens in new tab
<pivot-link
pivot-href="https://example.com"
pivot-target="_blank"
pivot-rel="noopener noreferrer"
>
External site (opens in new tab)
</pivot-link>Download
<pivot-link pivot-href="/files/report.pdf" pivot-download="annual-report.pdf">
Download Annual Report
</pivot-link>Accessible label override (pivot-aria-label)
<pivot-link
pivot-href="#article-1"
pivot-aria-label="Read more about the FCS launch"
>Read more</pivot-link
>