CogJS - Cognitive-Oriented Web Accessibility Toolkit

cog-toc

cog-toc is a declarative attribute that automatically generates an accessible Table of Contents from the headings inside a target content block. It’s ideal for long documents, multi-section forms, or content-heavy pages that benefit from structure and easy navigation.

What It Does

When used on a <nav cog-toc> element, CogJS finds the next sibling element and scans for all h1 through h4 headings. It injects a list of internal anchor links into the TOC, overrides existing heading IDs, and optionally adds a “Back to top” link at the bottom of each section if cog-toc-back is present.

<nav id="toc" cog-toc cog-toc-back></nav>

<article>
  <h2>Introduction</h2>
  <p>Welcome to our guide.</p>

  <h2>Usage</h2>
  <p>How to implement the feature.</p>

  <h2>Advanced Settings</h2>
  <p>Customization options and behavior.</p>
</article>

How It Works

• TOC is built from h1 to h4 elements inside the next sibling of the TOC container
• Existing id attributes on headings are overwritten with sanitized, predictable IDs
• Anchor links use internal #ids to enable smooth or instant scrolling
• When cog-toc-back is used, a “Back to top” link is inserted after each section

Default Styling

CogJS provides default visual styling for the TOC and section links. You can override them with your own CSS or use a custom theme via cogConfig.

.cog-toc {
  font-family: sans-serif;
  font-size: 0.95rem;
  background: #f4f4f4;
  padding: 1rem;
  border-radius: 6px;
  max-width: 300px;
}

.cog-toc a {
  display: block;
  color: #007acc;
  text-decoration: none;
  margin-bottom: 0.5rem;
}

.cog-toc a:hover {
  text-decoration: underline;
}

.cog-toc-back {
  display: inline-block;
  margin-top: 1rem;
  font-size: 0.85rem;
  color: #555;
}

Accessibility Considerations

• Semantic: Uses <nav> and aria-label for screen reader clarity
• Keyboard Friendly: All links are focusable and navigable via keyboard
• Visual Hierarchy: Indentation or nesting can be added for deeper levels

Testing cog-toc

// Test Checklist
// - Add  before a content block
// - Confirm TOC links navigate to the correct headings
// - Ensure "Back to top" links work when cog-toc-back is used
// - Test keyboard and screen reader interaction

Best Practices for cog-toc

• Limit to One TOC Per Page: Multiple TOCs can confuse screen reader users
• Structure Content Clearly: Use consistent heading levels (e.g. h2 → h3)
• Use cog-toc with Articles: Ideal for blog posts, guides, manuals, and wikis
• Combine With cog-outline: For nested navigation across page sections