Nav ToC

Last modified:

In-page table of contents-style navigation. Nav ToC is our 4th-level navigation.

Example of Nav ToC - default

<BcNavToc isHeadingHidden>
    <BcNavToc.Anchor href='#content'>
      Navigation item
  <BcNavToc.Item isActive>
    <BcNavToc.Anchor href="#content">
      Active navigation item
    <BcNavToc.Anchor href="#content">
      Navigation item

React documentation

Last modified:

BcNavToC Props

BcNavToC is the parent wrapper component for the navigation’s list. It accepts following props:

sizestringfalseSets the font size
classNamestringfalseTo add additional classes
isHeadingHiddenbooleanfalsefalseTo hide the navigation heading
isFixedbooleanfalsefalseSets position fixed
isStickybooleanfalsefalseSets position sticky

Any other props will be passed to the <nav> element.

Extended types: React.HTMLAttributes<HTMLOListElement>

BcNavToc.Item Props

BcNavToc.Item holds the item in table of content navigation, it accepts the following props.

Pass BcNavToc.Anchor or any other component that renders an anchor element.

childrenstring or ReactElementtrueTo show the item content

Any other props will be passed to the <li> element.

Extended types: React.HTMLAttributes<HTMLLIElement>

BcNavToc.Anchor Props

BcNavToc.Anchor is an anchor tag with .bc-nav-toc__link className.

There is no specific props for this component but it extends the html attributes of the base anchor element.

Pass badges or icons into this component.

childrenReactNodetrueContent to show inside the anchor element
hrefstringtrueThe URL that the hyperlink points to

So any other props will be passed to the <a> element.

Extended types: React.AnchorHTMLAttributes<HTMLAnchorElement>


Last modified:

ToC links should be in an ordered list (<ol>).

Links must be in the order in which they appear on the page.

Link to a wrapping <section> or <article> for each heading instead of targeting the headings.

Nested lists and links are not supported (see Rationale section).

Smooth scrolling

By default scroll jumps are instant and can feel abrupt.

Use CSS’ scroll-behavior: smooth to enable a ‘smooth’ scrolling animation. Browsers use native OS scrolling and respect associated OS scroll behavior preferences, eg. shortened animation timing.

Place the scroll-behavior style on a high-level DOM node, eg. the <body> or <main>.

⚠️ Poor performance can happen when using smooth scrolling on very long or complex pages, in particular on mobile devices.


Last modified:

Use it for in-page Table of Contents, linking only to resources on the current page a user is on.

Do not link off-page using this navigation.

Nav ToC is built to support both static templating and dynamic web pages.

Current active item styling (orange border) is only available on dynamic pages (see Accessibility section).

2 variants exist:

  • .bc-nav-toc--lg: Increases component font-size to $bc-font-size--lg
    • Spacing and faux-border dimensions are set in ems to scale proportionally.
  • .bc-nav-toc--fixed: Sets position: fixed for layout placement in sidebars.

Add a “Back to top” link within the navigation component only when it’s position: fixed.

When not using the fixed-position layout or static templating, optionally add a “Back to top” link to the header or footer of each section being linked to.


Last modified:

To improve semantics, usability, and overall accessibility this component:

  • Uses a wrapping <nav> element
  • Gives a contextual HTML heading for this list of navigation links (eg. “On this page”)
  • Anchors must only link to (unique) IDs on the current page
  • Anchors must only use aria-current if the page’s routing is dynamically handled in JS:
    • Why? In static templating and URL pathing, when only the ID changes the aria-current attribute cannot be updated without JavaScript.
    • If the navigation is position: fixed as the user scrolls, update aria-current to match the scroll position.

“Back to top” icon accessibility

Directional icons are additive to the link text and can be confusing to assistive technologies.

Set aria-hidden on the icon to remove it from the Accessibility Tree, eg:

<div class="bc-hint">
  <span aria-hidden="true">&uarr; </span>
  <a href="#main">Back to top</a>


Last modified:

Users are familiar with table of contents patterns, both in print and on the Web.

A table of contents helps users understand how longer pages are structured.

ToC links let users navigate to and between on-page content.

The list intentionally does not support nesting to keep the navigation simpler and to encourage thoughtful structuring of longer pages.

Anchors must only link to on-page content because mixing on-page and off-page links is inconsistent and confusing.

Despite being an ordered list the numbered list-style are not shown. If you need a lexically ordered navigation see the Stepped nav component.

See also

Last modified: