Pivot Docs

    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-label when set via pivot-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-link is slotted inside a pivot-text[pivot-on-dark] element, it inherits dark-surface link colors automatically (see Inheriting dark context from pivot-text above).

    References


    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.