The table-of-contents Element

The table-of-contents element represents a navigable list of headings for some content. This component is able to automatically generate links needed to navigate to all the different headings in an article.

<table-of-contents
	for="main-content"
	aria-label="Table of Contents"
></table-of-contents>

<section id="main-content">
	<h2 id="one">One</h2>
	<h3 id="one-one">One One</h3>
	<h3 id="one-two">One Two</h3>
	<h2 id="two">Two</h2>
</section>

Installation

You can import through CDN:

<script type="module" src="https://unpkg.com/@auroratide/table-of-contents/lib/define.js"></script>

Or, you may install through NPM and include it as part of your build process:

$ npm i @auroratide/table-of-contents

import '@auroratide/table-of-contents/lib/define.js'

Usage

table-of-contents is a markup element that you can use in your HTML document.

The for attribute can be set to the id of an element on the page. If you supply this, the table-of-contents will automatically generate a list of links to headings in the chosen element.

For this, your content must conform to the following:

• Headings in your content are defined with the h1 through h6 tags.
• Headings do not skip levels (this is good accessibility practice anyway).
• Each heading has an id defined that uniquely identifies it.
• The first heading can be of any level, as long as no heading afterward is higher than it.
  • For instance, if your content starts with an h2, there should not be an h1 later in the document.

The following is a example of what a good heading structure looks like:

<section id="main-content">
	<h2 id="one">One</h2>
	<h3 id="one-one">One One</h3>
	<h3 id="one-two">One Two</h3>
	<h4 id="one-two-one">One Two One</h4>
	<h2 id="two">Two</h2>
	<h3 id="two-one">Two One</h3>
	<h4 id="two-one-one">Two One One</h4>
	<h3 id="two-two">Two Two</h3>
</section>

Labelling the Table of Contents

The table of contents represents a navigation landmark. Therefore, it is good accessibility practice to label it.

This can be done with aria-label.

<table-of-contents
	for="main-content"
	aria-label="Table of Contents"
></table-of-contents>

Manually Rebuilding the List

The table-of-contents element does not automatically react to changes in your document structure.

Instead, the element provides a Javascript build() method so that you may define your own reaction logic, should it be needed. The build() method regenerates the list of links for the identified section.

const toc = document.querySelector("table-of-contents")

toc.build()

Fallback List

Children of the table-of-contents may serve as a fallback in case Javascript is disabled, fails, or takes a long time to execute. This is optional, but enhances the accessibility of your page.

Once the list generation occurs, the visible content is replaced with the new list. The fallback list will continue to exist in the DOM.

<table-of-contents for="main-content" aria-label="Contents">
	<ol>
		<li><a href="#one">One</a></li>
		<li><a href="#two">Two</a></li>
	</ol>
</table-of-contents>

CSS Customization

Since these are native custom elements, they can be styled the same way as regular HTML elements.

The anchor part exposes the links generated by the component.

table-of-contents::part(anchor) {
	color: red;
}

Accessibility

This custom element is built with accessibility in mind! A table of contents is a navigational landmark, and therefore the table-of-contents element gets granted the navigation role.

The best practice is to label your table of contents so readers know the content it is for. You may use aria-label or aria-labelledby for this.