Add Accessible Shareable Anchor Links To Headings – Heading Anchors

Heading Anchors is a lightweight web component that automatically adds anchor links to heading elements (h1 ~ h6) with unique ID attributes. This can enhance the shareability of webpage sections while ensuring that your anchor links remain fully accessible.

This component was inspired by ‘Are your Anchor Links Accessible?‘ and ensures your anchor links are usable by everyone, including those using screen readers. It achieves this by creating a sibling anchor link for each heading, positioned alongside the heading text but separate in the HTML structure for optimal accessibility.

Heading Anchors prioritizes accessibility by using the CSS Anchoring API when available. If the browser doesn’t support the API, it gracefully falls back to JavaScript positioning. It also meticulously matches the font styling of the corresponding heading to provide a consistent visual experience. The placeholder character (defaults to ‘#’) it inserts prevents content reflow when interacting with the anchor link.

How to use it:

1. Install & download.

# NPM
$ npm install @zachleat/heading-anchors

2. Import the Heading Anchors into your project.

<script type="module" src="/heading-anchors.js"></script>

3. Wrap your headings and content within the <heading-anchors> custom element.

<heading-anchors>
  <h1 id="heading-1">Heading 1</h1>
  <p>Content 1</p>
  <h2 id="heading-2">Heading 2</h2>
  <p>Content 1.2</p>
</heading-anchors>

The component will transform a basic heading like this:

<h2 id="heading-2">Heading 2</h2>

Into an enhanced, accessible version:

<h2 id="heading-2">Heading 2<span aria-hidden="true" class="ha-placeholder" style="anchor-name: --ha_0_0;">#</span></h2>
<a href="#heading-2" class="ha" style="position-anchor: --ha_0_0; font: 700 24px system-ui, sans-serif;"><span class="ha-visualhide">Jump to section titled: Heading 2</span><span aria-hidden="true">#</span></a>

4. Use the selector property to define which heading levels should have anchor links.

<heading-anchors selector="h2,h3">
  ...
</heading-anchors>

5. Exclude Specific Headings: Add the data-ha-exclude attribute to any heading you want to skip.

<h2 id="heading-2" data-ha-exclude>Heading 2 (Skipped)</h2>

6. Customize the accessible text within the anchor links using the prefix property.

<heading-anchors prefix="这是一个锚点">
  ...
</heading-anchors>

7. Modify the anchor character (default is ‘#’) using the content property.

<heading-anchors content="&">
<h2 id="heading-2">Heading 2</h2>
</heading-anchors>

8. Style the character using the ha-placeholder class in your CSS.

.ha-placeholder {
  /* Your styles here */
}

9. Add the following CSS to prevent layout shifts caused by the anchor character:

heading-anchors:not(:defined) :is(h2,h3,h4,h5,h6):after {
  content: "#";
  padding: 0 .25em;
  opacity: 0;
}