foot-notes

Progressive enhancement for footnotes with inline references and automatic collection.

Overview

The <foot-notes> component works with <foot-note> elements to create accessible footnotes. Without JavaScript, footnotes appear inline. With JavaScript, they become superscript links with a collected list at the bottom.

<p> The Vanilla Breeze framework<foot-note>Vanilla Breeze is an experimental component library.</foot-note> provides a layered approach. </p> <foot-notes></foot-notes>

Components

<foot-note>

The footnote reference element. Place inline within your content where you want a footnote marker.

Element Content Description
<foot-note> Text Contains the footnote text. Becomes a superscript link when enhanced.

<foot-notes>

The footnotes container. Place at the end of your content where you want footnotes collected.

Attribute Type Default Description
data-back-label string "Back to content" Accessible label for back-reference links.

Progressive Enhancement

The footnotes component demonstrates progressive enhancement principles.

Without JavaScript

When JavaScript is disabled or fails to load, footnotes remain inline within parentheses, keeping the content readable:

<!-- Renders as: --> The framework (Vanilla Breeze is an experimental component library) provides a layered approach.

With JavaScript

When JavaScript loads, the component:

  • Finds all <foot-note> elements before the <foot-notes>
  • Converts them to superscript numbered links
  • Collects footnote content into an ordered list
  • Adds back-reference links from each footnote

Basic Usage

Place <foot-note> elements inline where footnotes should appear, then add a single <foot-notes> element where the footnote list should be rendered.

<p>This is the first paragraph with a footnote<foot-note>This is the first footnote explaining something important.</foot-note> in the middle of the text.</p> <p>Here's another paragraph with multiple footnotes<foot-note>Second footnote.</foot-note> demonstrating how they<foot-note>Third footnote.</foot-note> are numbered automatically.</p> <foot-notes></foot-notes>

Custom Back Label

Use data-back-label to customize the accessible label for back-reference links.

<foot-notes data-back-label="Return to text"></foot-notes>

The default label is "Back to content". Customize it for internationalization or to match your site's terminology.

Long Form Content

Footnotes work well with longer articles and prose content.

How It Works

The component processes footnotes in the following steps:

  1. Collection: Finds all <foot-note> elements that appear before the <foot-notes> element in document order.
  2. Enhancement: Each <foot-note> gets:
    • A unique ID (e.g., fnref-1)
    • A data-enhanced attribute
    • The original content wrapped in a span
    • A superscript link to the footnote
  3. List Generation: An ordered list is created inside <foot-notes> with:
    • Each footnote's content
    • A back-reference link to the original location

Generated HTML

<!-- Original --> <foot-note>Footnote content</foot-note> <!-- Enhanced --> <foot-note id="fnref-1" data-enhanced> <span>Footnote content</span> <a href="#fn-1" aria-describedby="fn-1">[1]</a> </foot-note> <!-- Footnotes list --> <foot-notes> <ol> <li id="fn-1"> Footnote content <a href="#fnref-1" class="fn-backref" aria-label="Back to content">&#8617;</a> </li> </ol> </foot-notes>

Accessibility

ARIA Attributes

  • Footnote links have aria-describedby pointing to the footnote content
  • Back-reference links have aria-label for screen reader context

Navigation

  • Clicking a footnote number jumps to the footnote in the list
  • Clicking the back-reference returns to the original location
  • All links are keyboard accessible

Screen Reader Experience

Screen readers will:

  • Announce the footnote number as a link
  • Read the footnote content when navigating to it
  • Allow users to return to their reading position

Best Practices

  • Keep footnote content concise
  • Don't put essential information only in footnotes
  • Use footnotes for supplementary information, citations, or clarifications
  • Place <foot-notes> at the end of the content section

Styling

The component can be styled using CSS selectors.

/* Style the footnote reference links */ foot-note a { font-size: var(--font-size-sm); vertical-align: super; text-decoration: none; color: var(--color-interactive); } foot-note a:hover { text-decoration: underline; } /* Hide the inline content when enhanced */ foot-note[data-enhanced] > span { display: none; } /* Style the footnotes list */ foot-notes ol { font-size: var(--font-size-sm); border-block-start: var(--border-width-thin) solid var(--color-border); padding-block-start: var(--size-m); margin-block-start: var(--size-xl); } /* Style the back-reference link */ foot-notes .fn-backref { margin-inline-start: var(--size-2xs); text-decoration: none; }

Multiple Footnote Sections

You can have multiple <foot-notes> elements in a document. Each will collect only the footnotes that appear before it.

Sidenote Mode

Add data-mode="sidenotes" to <foot-notes> to place footnotes as margin annotations alongside the text instead of collecting them at the bottom. The authored markup is identical to regular footnotes.

<layout-text> <p> Gutenberg's printing press transformed European society.<foot-note>Johannes Gutenberg developed movable type around 1440 in Mainz, Germany.</foot-note> Before its invention, books were copied by hand in monasteries. </p> <foot-notes data-mode="sidenotes"></foot-notes> </layout-text>

Three-Layer Degradation

  1. No JS: <foot-note> content appears inline in parentheses — the standard progressive enhancement fallback.
  2. JS + narrow viewport: Falls back to numbered sidenotes that collapse to bordered blocks via CSS responsive rules.
  3. JS + wide viewport: Superscript numbered links at each reference point, with note content floated into the margin alongside the text.

Per-Note Opt-Out

Individual footnotes can opt out of sidenote placement with data-side="false". These notes are collected into the footnote list instead. Useful for longer notes that would overwhelm the margin.

<foot-note data-side="false">This note always goes to the footnote list, even in sidenote mode.</foot-note>

Sidenote Mode Attributes

On <foot-notes>

Attribute Value Description
data-mode "sidenotes" Enables sidenote mode — notes are placed as margin annotations instead of collected at the bottom.

On <foot-note>

Attribute Value Description
data-side "false" Opts this note out of sidenote placement. It will appear in the collected footnote list instead.

Use Cases

Academic Writing

Citations and references in scholarly articles:

<p>Research shows significant improvements<foot-note>Smith et al., "Progressive Enhancement Study," Journal of Web Development, 2024.</foot-note> in user experience.</p>

Legal Documents

Definitions and clarifications in terms of service:

<p>The Service<foot-note>"Service" refers to the web application provided at example.com.</foot-note> may be modified at any time.</p>

Technical Documentation

Additional context or caveats:

<p>This feature requires ES2022<foot-note>Specifically, private class fields and top-level await.</foot-note> support.</p>

Limitations

  • Footnote numbering is determined by document order, not insertion order
  • The component doesn't support dynamically added footnotes after initial render
  • Rich HTML content in footnotes (links, formatting) is supported but may require additional styling