View this page with live demos!
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.
One
One One
One Two
Two
<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
throughh6
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 anh1
later in the document.
- For instance, if your content starts with an
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.