CivicTheme
  • Docs
  • Changelog
  • Getting started
    • Introduction
    • Installation
    • Getting help
    • Security policy
    • Partnerships
  • Installation
    • Drupal theme
  • Contributing
    • Contribution model
    • Contribution basics
    • Small contribution spec
    • Medium contribution spec
    • Major (RFC-level) contribution spec
    • Code of conduct
    • Figma contributions
  • Components
    • Component list
    • Atoms
      • Button
      • Chip
      • Content link
      • Check box
      • Field description
      • Field message
      • Fieldset
      • Label
      • Radio
      • Select
      • Textarea
      • Text field
      • Heading
      • Link
      • Paragraph
      • Popover
      • Quote
      • Table
      • Tag
      • Text list
    • Molecules
      • Accordion
      • Attachment
      • Breadcrumb
      • Callout
      • Event Card
      • Field
      • Figure
      • Group filter
      • Logo
      • Map
      • Navigation card
      • Next step
      • Pagination
      • Promo card
      • Search
      • Service card
      • Single filter
      • Snippet
      • Subject Card
      • Table of Contents
      • Tabs
      • Tag List
      • Tooltip
      • Video Player
    • Organisms
      • Alert
      • Banner
      • Campaign
      • Footer
      • Header
      • List
      • Message
      • Mobile Navigation
      • Navigation
      • Promo
      • Side Navigation
      • Skip link
      • Slider
      • Social links
  • Content Authoring
    • Overview
    • Global settings
      • Favicon
      • Header
        • Site slogan
        • Header logos
        • Primary navigation
        • Secondary navigation
      • Banner
      • Search
      • Link
      • Skip link
      • Side navigation
      • Signup
      • Footer
        • Footer logo
        • Social links
        • Footer navigation
        • Acknowledgement of Country
        • Copyright
      • Colours
    • Content types
      • Page
        • Configure the banner
      • Event
      • Alert
    • Content components
      • Accordion
      • Automated list
      • Attachment
      • Callout
      • Campaign
      • Content
        • Quote
      • iFrame
      • Manual List
        • Event card
        • Event reference card
        • Navigation card
        • Navigation reference card
        • Promo card
        • Promo reference card
        • Publication card
        • Service card
        • Subject card
        • Subject reference card
        • Snippet
      • Map
      • Next step
      • Promo
      • Slider
      • Webform
    • Vocabularies
      • Topics
      • Site sections
    • User accounts & roles
Powered by GitBook
On this page
  • When to use
  • When not to use
  • Best practice guidelines
  • Variations
  • Accessibility
  • Security
  • Component inspiration and uplift
  • User research on this component
  • Known issues
  • More research needed
  • Help improve this component
  • Resources
  • References
  • Changelog
  • Contact us

Was this helpful?

Edit on GitHub
Export as PDF
  1. Components
  2. Molecules

Table of Contents

A navigational component that helps users understand the structure of the current page and jump directly to specific sections.

When to use

Use the table of contents component when:

  • Content pages are long with multiple sections and subsections

  • Users need to quickly scan the structure of a page

  • You want to provide easy navigation to different sections of a long document

  • You need to improve navigation within content-heavy pages such as information guides, policy documentation, or lengthy articles

When not to use

Do not use the table of contents component when:

  • The page has minimal content or only a few short sections

  • The page structure is extremely simple with limited headings

  • Content is primarily visual rather than text-based

  • The space available is too limited to display the table of contents effectively

  • The content follows a step-by-step wizard pattern where linear progression is required


Best practice guidelines

  • Accurate reflection: Ensure the table of contents accurately reflects the heading structure of the page, maintaining the correct hierarchy of headings.

  • Concise entries: Keep table of contents entries concise and clear, ideally no more than one line per item.

  • Logical structure: Maintain a clear visual hierarchy that shows the relationship between sections and subsections through appropriate indentation.

  • Responsive design: Adapt the presentation of the table of contents for different screen sizes, potentially converting to a collapsible component on mobile devices.

  • Persistent access: Consider making the table of contents "sticky" or persistent on long pages so users always have access to navigation as they scroll.

  • Visual distinction: Ensure the table of contents is visually distinct from the main content while still following the design system's visual language.

  • Highlight current section: Indicate the user's current position in the document by highlighting the corresponding entry in the table of contents.

  • Avoid overloading: Only include meaningful section headers (H2, H3) in the table of contents—avoid including every heading level as this can create visual clutter.

Variations

The table of contents component is available in the following variations:

Standard table of contents:

  • Default styling, typically placed at the top of a content page before the main content begins

  • Includes section titles linked to their respective sections on the page

Sticky/fixed table of contents:

  • Remains visible as the user scrolls down the page, typically positioned in a sidebar

  • Provides constant access to navigation regardless of scroll position

Collapsible table of contents:

  • Can be expanded or collapsed to save space, particularly useful on mobile devices

  • Usually displays a "Table of contents" or "In this page" header with an expansion indicator

Nested table of contents:

  • Shows multiple levels of headings with clear visual hierarchy

  • Provides more detailed navigation for complex documents


Accessibility

This component has been assessed against WCAG 2.2 accessibility guidelines. Based on the CivicTheme v1.7.0 Accessibility Assessments, the following standards were tested for this component:

Summary of test results:

  • All WCAG 2.2 Level A guidelines passed

  • All WCAG 2.2 Level AA guidelines passed

  • Not tested against all WCAG 2.2 Level AAA guidelines

Key accessibility features:

  • Proper heading structure and semantic markup

  • Keyboard navigability between all links

  • Visible focus indicators for keyboard users

  • Sufficient color contrast for text and interactive elements

  • Proper ARIA roles and attributes to enhance screen reader compatibility

Security

The table of contents component does not process user data or handle sensitive information, minimizing security concerns. Standard web security practices should be followed during implementation.

Component inspiration and uplift

This component has been modelled after the In-page Nav component in the former Australian Government Design System (AGDS). It has been uplifted by Salsa Digital, as the custodian of the CivicTheme Design System, in the following ways:

  • Created stronger contrast/distinction between resting and hover states of section links

  • Used smaller text sizes for section links to better establish content hierarchy

  • Improved interaction states to match CivicTheme's design language

  • Enhanced mobile responsiveness for improved usability on smaller screens

These uplifts were based on user testing that showed users preferred clearer visual indicators for interactive elements and a more compact design that doesn't overwhelm the main content.


User research on this component

★★★★☆ Confidence rating = High (Based on controlled testing)

User research has been conducted by CivicTheme's design team on the table of contents component's usability and effectiveness. This involved multiple rounds of testing with a diverse group of users.

Key findings from the research:

  • Users appreciate the ability to quickly scan page structure before reading content

  • Sticky/fixed variations were particularly valued on long pages

  • Some users initially overlooked the component, leading to design improvements that increase visual prominence

  • Testing confirmed the importance of current section highlighting to help users maintain their bearings

The research validated the table of contents as an essential navigation aid for content-heavy pages and informed several usability improvements to the component.

Known issues

  • Scroll synchronization: Some users experience issues with the highlighted section not always accurately reflecting their current position on the page, particularly when sections are close together.

  • Mobile usability: On smaller screens, the table of contents can take up significant vertical space, potentially pushing important content below the fold if not implemented as a collapsible component.

  • Heading depth: There is occasional confusion about which heading levels should be included in the table of contents, with some users expecting to see deeper heading levels than are typically shown.

More research needed

More user research is needed in the following areas:

  • Optimal positioning of the table of contents on different page layouts

  • User preferences regarding dynamic vs. static table of contents on mobile devices

  • Effectiveness of different visual treatments for indicating the current section

  • Usage patterns across different user demographics and contexts

If you have conducted user research that addresses any of these gaps, you can submit your research findings to help improve this component.

Help improve this component

To help make this component useful and up-to-date, you can:

  • Contribute to our table of contents component discussion on the CivicTheme GitHub repository

  • Submit your user research findings to help improve the component

  • Propose a change to the table of contents component via a pull request

  • Report bugs or issues you encounter when implementing this component


Resources

  • Storybook

  • GitHub

References

  • Nielsen, J. (2010). "Scrolling and Attention." Nielsen Norman Group.

  • Loranger, H. (2014). "Minimize Design Risk by Focusing on Outcomes and Context." Nielsen Norman Group.

  • W3C Web Accessibility Initiative. (2021). "WAI-ARIA Authoring Practices 1.2: Navigation."

  • Australian Government Design System Documentation (Archived)

Changelog

Version
Date
Description

1.0.0

Initial release

Initial component release

1.7.0

March 2024

Updated to improve contrast between states and optimize for mobile

Contact us

PreviousSubject CardNextTabs

Last updated 1 month ago

Was this helpful?

Check out our to learn more.

If you have a question about the CivicTheme design system or need our help, visit the page for guidance.

contributing section
Figma
Getting Help