Example of Nav ToC - default
<BcNavToc isHeadingHidden> <BcNavToc.Item> <BcNavToc.Anchor href='#content'> Navigation item </BcNavToc.Anchor> </BcNavToc.Item> <BcNavToc.Item isActive> <BcNavToc.Anchor href="#content"> Active navigation item </BcNavToc.Anchor> </BcNavToc.Item> <BcNavToc.Item> <BcNavToc.Anchor href="#content"> Navigation item </BcNavToc.Anchor> </BcNavToc.Item> </BcNavToc>
React documentation
Last modified:
BcNavToC Props
BcNavToC is the parent wrapper component for the navigation’s list. It accepts following props:
| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
| size | string | false | Sets the font size | |
| className | string | false | To add additional classes | |
| isHeadingHidden | boolean | false | false | To hide the navigation heading |
| isFixed | boolean | false | false | Sets position fixed |
| isSticky | boolean | false | false | Sets 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.
| Prop | Type | Required? | Default | Description |
|---|---|---|---|---|
| children | string or ReactElement | true | To 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.
| Prop | Type | Required? | Default | Description |
|---|---|---|---|---|
| children | ReactNode | true | Content to show inside the anchor element | |
| href | string | true | The URL that the hyperlink points to |
So any other props will be passed to the <a> element.
Extended types: React.AnchorHTMLAttributes<HTMLAnchorElement>
HTML
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.
Design
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).
Nav ToC variants
2 variants exist:
.bc-nav-toc--lg: Increases componentfont-sizeto$bc-font-size--lg- Spacing and faux-border dimensions are set in
ems to scale proportionally.
- Spacing and faux-border dimensions are set in
.bc-nav-toc--fixed: Setsposition: fixedfor layout placement in sidebars.
When to include “Back to top” links
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.
Accessibility
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-currentif the page’s routing is dynamically handled in JS:- Why? In static templating and URL pathing, when only the ID changes the
aria-currentattribute cannot be updated without JavaScript. - If the navigation is
position: fixedas the user scrolls, updatearia-currentto match the scroll position.
- Why? In static templating and URL pathing, when only the ID changes the
“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">↑ </span>
<a href="#main">Back to top</a>
</div>
Rationale
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: