Skip to content

Link

The link system with four cues on every link and one more per kind, named by data-link.

<div class="link-scroll" role="region" aria-label="A text link in each state" tabindex="0">
<table class="link-states">
  <caption class="cap-sr-only">A text link in each state</caption>
  <thead>
    <tr><th scope="col">At rest</th><th scope="col">Hover</th><th scope="col">Pressed</th><th scope="col">Visited</th><th scope="col">Focus</th></tr>
  </thead>
  <tbody>
    <tr>
      <td><a href="/writing/field-notes">Field notes</a></td>
      <td><a href="/writing/field-notes">Field notes</a></td>
      <td><a href="/writing/field-notes">Field notes</a></td>
      <td><a href="/writing/field-notes">Field notes</a></td>
      <td><a href="/writing/field-notes">Field notes</a></td>
    </tr>
  </tbody>
</table>
</div>
<p>In a sentence: the <a href="/writing/field-day">field day notes</a> sit beside the <a href="/writing/spring-survey">spring garden survey</a>, and a long link wraps with its tint on each line: <a href="/writing/why-field-notebooks-keep-coming-back">why field notebooks keep coming back after a century of being forgotten</a>.</p>

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/link.css";
import { underPath, mayPrefetch } from "capsomer/behavior/link";

Usage

<a href="https://example.org/" data-link="away" rel="external">Example Org<span class="cap-sr-only"> (opens another site)</span></a>
<a href="https://fieldnotes.example.com/" data-link="away" rel="external"><img class="cap-link-icon" src="/link-icons/fieldnotes.example.com.png" alt="" width="16" height="16">Field Notes<span class="cap-sr-only"> (opens another site)</span></a>
<a href="https://germomics.com" data-link="family" data-site="germomics">Germomics</a>
<a href="/files/survey-protocol.pdf" data-link="file">The survey protocol</a> <span class="cap-link-meta">PDF, 2 MB</span>
<a href="#methods" data-link="jump">Methods</a>
<a href="mailto:editor@example.com" data-link="email">Write to the editor</a>
<a href="tel:+15550100" data-link="phone">Call the office</a>
<a href="/es/" hreflang="es" data-link="lang">Read it</a> <span class="cap-link-meta" lang="es">Español</span>
<sup><a href="#fn-1" id="fnref-1" class="cap-footnote-ref" aria-describedby="footnote-label">1</a></sup>
<a href="#fnref-1" data-footnote-backref aria-label="Back to reference 1">↩</a>
<a href="/writing/sampling" data-link="xref">sampling</a>
<a href="https://doi.org/10.5555/12345678" data-link="address" rel="external">doi.org/10.5555/12345678<span class="cap-sr-only"> (opens another site)</span></a>
<p><a href="/writing/part-two" data-link="next">Part two: the notebooks</a></p>
<h2><a href="/writing/field-notebooks">Why field notebooks keep coming back</a></h2>
<a href="/tags/survey" data-link="tag">survey</a>

Examples

Each kind, with its one cue, in each state

<div class="link-scroll" role="region" aria-label="Every kind of link in each state" tabindex="0">
<table class="link-states" id="link-kinds">
  <caption class="cap-sr-only">Every kind of link in each state</caption>
  <thead>
    <tr><th scope="col">Kind</th><th scope="col">At rest</th><th scope="col">Hover</th><th scope="col">Pressed</th><th scope="col">Visited</th></tr>
  </thead>
  <tbody>
    <tr>
      <th scope="row">away</th>
      <td><a href="https://example.org/" data-link="away">Example Org<span class="cap-sr-only"> (opens another site)</span></a></td>
      <td><a href="https://example.org/" data-link="away">Example Org<span class="cap-sr-only"> (opens another site)</span></a></td>
      <td><a href="https://example.org/" data-link="away">Example Org<span class="cap-sr-only"> (opens another site)</span></a></td>
      <td><a href="https://example.org/" data-link="away">Example Org<span class="cap-sr-only"> (opens another site)</span></a></td>
    </tr>
    <tr>
      <th scope="row">away, with the site's icon</th>
      <td><a href="https://fieldnotes.example.com/" data-link="away" rel="external"><img class="cap-link-icon" src="./specimen/outside-icon.svg" alt="" width="16" height="16">Field Notes<span class="cap-sr-only"> (opens another site)</span></a></td>
      <td><a href="https://fieldnotes.example.com/" data-link="away" rel="external"><img class="cap-link-icon" src="./specimen/outside-icon.svg" alt="" width="16" height="16">Field Notes<span class="cap-sr-only"> (opens another site)</span></a></td>
      <td><a href="https://fieldnotes.example.com/" data-link="away" rel="external"><img class="cap-link-icon" src="./specimen/outside-icon.svg" alt="" width="16" height="16">Field Notes<span class="cap-sr-only"> (opens another site)</span></a></td>
      <td><a href="https://fieldnotes.example.com/" data-link="away" rel="external"><img class="cap-link-icon" src="./specimen/outside-icon.svg" alt="" width="16" height="16">Field Notes<span class="cap-sr-only"> (opens another site)</span></a></td>
    </tr>
    <tr>
      <th scope="row">family</th>
      <td><a href="https://germomics.com" data-link="family" data-site="germomics">Germomics</a></td>
      <td><a href="https://germomics.com" data-link="family" data-site="germomics">Germomics</a></td>
      <td><a href="https://germomics.com" data-link="family" data-site="germomics">Germomics</a></td>
      <td><a href="https://germomics.com" data-link="family" data-site="germomics">Germomics</a></td>
    </tr>
    <tr>
      <th scope="row">file</th>
      <td><a href="/files/survey-protocol.pdf" data-link="file">Survey protocol</a> <span class="cap-link-meta">PDF, 2 MB</span></td>
      <td><a href="/files/survey-protocol.pdf" data-link="file">Survey protocol</a> <span class="cap-link-meta">PDF, 2 MB</span></td>
      <td><a href="/files/survey-protocol.pdf" data-link="file">Survey protocol</a> <span class="cap-link-meta">PDF, 2 MB</span></td>
      <td><a href="/files/survey-protocol.pdf" data-link="file">Survey protocol</a> <span class="cap-link-meta">PDF, 2 MB</span></td>
    </tr>
    <tr>
      <th scope="row">jump</th>
      <td><a href="#methods" data-link="jump">Methods</a></td>
      <td><a href="#methods" data-link="jump">Methods</a></td>
      <td><a href="#methods" data-link="jump">Methods</a></td>
      <td><a href="#methods" data-link="jump">Methods</a></td>
    </tr>
    <tr>
      <th scope="row">email</th>
      <td><a href="mailto:editor@example.com" data-link="email">Write to the editor</a></td>
      <td><a href="mailto:editor@example.com" data-link="email">Write to the editor</a></td>
      <td><a href="mailto:editor@example.com" data-link="email">Write to the editor</a></td>
      <td><a href="mailto:editor@example.com" data-link="email">Write to the editor</a></td>
    </tr>
    <tr>
      <th scope="row">phone</th>
      <td><a href="tel:+15550100" data-link="phone">Call the office</a></td>
      <td><a href="tel:+15550100" data-link="phone">Call the office</a></td>
      <td><a href="tel:+15550100" data-link="phone">Call the office</a></td>
      <td><a href="tel:+15550100" data-link="phone">Call the office</a></td>
    </tr>
    <tr>
      <th scope="row">lang</th>
      <td><a href="/es/" hreflang="es" data-link="lang">Read it</a> <span class="cap-link-meta" lang="es">Español</span></td>
      <td><a href="/es/" hreflang="es" data-link="lang">Read it</a> <span class="cap-link-meta" lang="es">Español</span></td>
      <td><a href="/es/" hreflang="es" data-link="lang">Read it</a> <span class="cap-link-meta" lang="es">Español</span></td>
      <td><a href="/es/" hreflang="es" data-link="lang">Read it</a> <span class="cap-link-meta" lang="es">Español</span></td>
    </tr>
    <tr>
      <th scope="row">footnote</th>
      <td>A claim.<sup><a href="#fn-1" class="cap-footnote-ref" aria-describedby="link-notes">1</a></sup></td>
      <td>A claim.<sup><a href="#fn-1" class="cap-footnote-ref" aria-describedby="link-notes">1</a></sup></td>
      <td>A claim.<sup><a href="#fn-1" class="cap-footnote-ref" aria-describedby="link-notes">1</a></sup></td>
      <td>A claim.<sup><a href="#fn-1" class="cap-footnote-ref" aria-describedby="link-notes">1</a></sup></td>
    </tr>
    <tr>
      <th scope="row">xref</th>
      <td><a href="/writing/sampling" data-link="xref">Sampling</a></td>
      <td><a href="/writing/sampling" data-link="xref">Sampling</a></td>
      <td><a href="/writing/sampling" data-link="xref">Sampling</a></td>
      <td><a href="/writing/sampling" data-link="xref">Sampling</a></td>
    </tr>
    <tr>
      <th scope="row">address</th>
      <td><a href="https://doi.org/10.5555/12345678" data-link="address" rel="external">doi.org/10.5555/12345678<span class="cap-sr-only"> (opens another site)</span></a></td>
      <td><a href="https://doi.org/10.5555/12345678" data-link="address" rel="external">doi.org/10.5555/12345678</a></td>
      <td><a href="https://doi.org/10.5555/12345678" data-link="address" rel="external">doi.org/10.5555/12345678</a></td>
      <td><a href="https://doi.org/10.5555/12345678" data-link="address" rel="external">doi.org/10.5555/12345678</a></td>
    </tr>
    <tr>
      <th scope="row">next</th>
      <td><a href="/writing/part-two" data-link="next">Part two</a></td>
      <td><a href="/writing/part-two" data-link="next">Part two</a></td>
      <td><a href="/writing/part-two" data-link="next">Part two</a></td>
      <td><a href="/writing/part-two" data-link="next">Part two</a></td>
    </tr>
    <tr>
      <th scope="row">tag</th>
      <td><a href="/tags/survey" data-link="tag">survey</a></td>
      <td><a href="/tags/survey" data-link="tag">survey</a></td>
      <td><a href="/tags/survey" data-link="tag">survey</a></td>
      <td><a href="/tags/survey" data-link="tag">survey</a></td>
    </tr>
  </tbody>
</table>
</div>
<p class="cap-sr-only" id="link-notes">Footnotes</p>

title: a heading that is a link, its arrow on hover or focus

<div class="link-titles">
  <h3><a href="/writing/field-notebooks">Why field notebooks keep coming back</a></h3>
  <h3><a href="/writing/field-notebooks">Why field notebooks keep coming back</a></h3>
</div>

family: every site's icon

<ul class="link-sites" id="link-family">
  <li><a href="https://dustinedwards.info" data-link="family" data-site="dustinedwards">dustinedwards.info</a></li>
  <li><a href="https://germomics.com" data-link="family" data-site="germomics">Germomics</a></li>
  <li><a href="https://julieedwards.info" data-link="family" data-site="julieedwards">Julie Edwards</a></li>
  <li><a href="https://foxing.app" data-link="family" data-site="foxing">Foxing</a></li>
  <li><a href="https://foxhoundapp.com" data-link="family" data-site="foxhound">Foxhound</a></li>
  <li><a href="https://txasm.org" data-link="family" data-site="txasm">Texas Branch ASM</a></li>
  <li><a href="https://biosciencewriters.com" data-link="family" data-site="bsw">BioScience Writers</a></li>
  <li><a href="https://carrel.dustinedwards.info" data-link="family" data-site="carrel">Carrel</a></li>
  <li><a href="https://capsid.dustinedwards.info" data-link="family" data-site="capsid">Capsid</a></li>
  <li><a href="https://capsomer.dustinedwards.info" data-link="family" data-site="capsomer">Capsomer</a></li>
  <li><a href="https://prelum.dustinedwards.info" data-link="family" data-site="prelum">Prelum</a></li>
  <li><a href="https://enarratio.dustinedwards.info" data-link="family" data-site="enarratio">Enarratio (no icon yet)</a></li>
</ul>

tag: a post's tags

<p>Filed under <a href="/tags/survey" data-link="tag">survey</a> <a href="/tags/history" data-link="tag">history</a> <a href="/tags/gardens" data-link="tag">gardens</a></p>

Found without the attribute

<ul id="link-fallbacks">
  <li>Another site: <a href="https://example.net/" rel="external">Example Net</a>, and a new tab: <a href="https://example.org/archive" target="_blank">the archive</a></li>
  <li>A download: <a href="/files/survey.zip" download>the survey data</a>, and a file by its ending: <a href="/files/annual-report.pdf">the annual report</a></li>
  <li>A place on this page, in running text: <a href="#results">the results</a></li>
  <li>Mail and phone: <a href="mailto:team@example.com">team@example.com</a>, <a href="tel:+15550100">555 0100</a></li>
  <li>A footnote as GFM writes it: a claim<sup><a href="#user-content-fn-1" id="user-content-fnref-1" data-footnote-ref aria-describedby="link-notes">2</a></sup>, and the way back: <a href="#user-content-fnref-1" data-footnote-backref aria-label="Back to reference 2">↩</a></li>
</ul>

A post: every kind in running text

 <main class="specimen-page link-post">
   <article data-context="prose">
     <h1>Why field notebooks keep coming back</h1>
     <p>Filed under <a href="/tags/survey" data-link="tag">survey</a> <a href="/tags/history" data-link="tag">history</a></p>
     <p>In 1917 a schoolteacher began a notebook of every bird in the town square, and by the 1930s whole towns kept them across Europe and America.<sup><a href="#fn-1" id="fnref-1" class="cap-footnote-ref" aria-describedby="post-notes">1</a></sup> Spreadsheets pushed the habit aside everywhere but a few villages, where the <a href="https://archive.example.net" data-link="away">Example Co archive<span class="cap-sr-only"> (opens another site)</span></a> kept collecting them. The <a href="/writing/sampling" data-link="xref">sampling</a> essay covers the method; this one is about the people.</p>
     <p>We read every notebook we could find (see <a href="#methods" data-link="jump">Methods</a>), and the charts of the counts are on <a href="https://germomics.com" data-link="family" data-site="germomics">Germomics</a>. The full protocol is <a href="/files/survey-protocol.pdf" data-link="file">the survey protocol</a> <span class="cap-link-meta">PDF, 2 MB</span>, and the review we leaned on is <a href="https://doi.org/10.5555/12345678" data-link="address" rel="external">doi.org/10.5555/12345678<span class="cap-sr-only"> (opens another site)</span></a>.</p>
     <p>There is a shorter version <a href="/es/writing/field-notebooks" hreflang="es" data-link="lang">in Spanish</a> <span class="cap-link-meta" lang="es">Español</span>. Questions go to <a href="mailto:editor@example.com" data-link="email">the editor</a>, and the office answers the phone at <a href="tel:+15550100" data-link="phone">555 0100</a>.</p>
     <h2 id="methods"><a href="#methods">Methods</a></h2>
     <p>We searched <a href="https://example.org/" data-link="away">Example Org<span class="cap-sr-only"> (opens another site)</span></a> for every notebook since 1990, and read the <a href="/writing/spring-survey">spring garden survey</a> again for the field sites.</p>
     <p><a href="/writing/field-notebooks-part-two" data-link="next">Part two: the notebooks</a></p>
     <section data-footnotes>
       <h2 id="post-notes" class="cap-sr-only">Footnotes</h2>
       <ol>
         <li id="fn-1"><p>The teacher's own account, 1917.
<a href="#fnref-1" data-footnote-backref aria-label="Back to reference 1">↩</a></p></li>
       </ol>
     </section>
   </article>
 </main>

API reference

LinkPrefetch

PropTypeRequiredDoes
excludereadonly string[]Yes
childrenReactNode

And every attribute of <anchor>.

And every attribute of <anchor>.

PropTypeRequiredDoes
hrefstringYes
newTabboolean
sponsoredboolean
childrenReactNode

And every attribute of <anchor>.

PropTypeRequiredDoes
variant"default" | "primary" | "secondary" | "danger" | "quiet" | "link"
size"xs" | "sm" | "default" | "lg"
iconOnlyboolean
wrapboolean
blockboolean
labelstring
awayboolean
newTabboolean
sponsoredboolean
tonever
hrefnever

And every attribute of <anchor>.

Functions

FunctionSignatureDoes
underPath(path: string, pattern: string): booleanTrue when path is pattern or sits under it, segment by segment and ignoring case, as the router matches. A pattern segment ":name" or "*" stands for any one segment: underPath("/b/handbook/export/epub", "/b/:project/export") is true, underPath("/administer", "/admin") false.
mayPrefetch(link: PrefetchLink): booleanWhether the link may prefetch. Never for a link that loads a whole document (reloadDocument), opens elsewhere (a target other than _self), downloads, leaves the app, points at a file, or goes under NEVER_PREFETCH or the app's exclude; /admin only from a page already under /admin.

CSS variables

VariableDefault
--link-after"\2193"
--link-alt", opens another site"
--link-before"\2709\FE0E"

Parts and data attributes

ClassIs
.cap-footnote-refits own class
.cap-link-iconits own class
.cap-link-metathe root
AttributeValues
data-footnote-backrefpresent or absent
data-footnote-refpresent or absent
data-linkaddress away email family file footnote jump next phone tag xref
data-sitebsw capsid capsomer carrel dustinedwards foxhound foxing germomics julieedwards prelum txasm
StateRead from
:activethe platform
:focus-visiblethe platform
:hoverthe platform
:visitedthe platform

Accessibility

KeyDoes
TabReaches the link; focus prefetches it in a React Router app, as hover does
EnterFollows it

Every mark is hidden: a glyph is written content: "↗" / "", an icon has no content and an img has alt="". The words are in the markup:

  • away: <span class="cap-sr-only"> (opens another site)</span> inside the link. A fallback with no attribute speaks it as the glyph's alt text instead (", opens another site", or ", opens in a new tab" for target="_blank").
  • file and lang: the meta is the words, read after the link.
  • email, phone, jump, family, xref, address, next, title, tag: the link text says it.
  • Footnotes: GFM's aria-describedby on the reference and aria-label="Back to reference 1" on the way back.
  • Every link is a real <a href>, announced as a link, opening in a new tab with the browser's own keys.
  • Marks are hidden from assistive technology and their words are in the contract (above). The sweep checks that every text link has the base cues, that each kind shows its mark, that marks are hidden, that visited and pressed differ from rest, and forced colors.
  • Text links are inline in a sentence (WCAG 2.5.8's inline exception); a tag pill and a footnote's way back reach the target size.
  • NavLink sets aria-current="page" on the link to the current route (React Router's own).

Last checked by hand: not yet. Automated: the sweep (test/sweep.spec.ts), the palette check, and test/unit/link.test.mjs (the prefetch rule, and the family icons against FAMILY_LINK_SITES).