TableOfContents

View source on GitHub
See recent changes on GitHub

TableOfContents component is used to navigate to anchors on a page. It also serves as an outline of a page’s content. TableOfContents is placed on the right side of the page, close to the main content block.

also known as Table of Contents, Page Navigation, Page Navigator, Secondary Nav

Figma:
Ready
Responsive:
Ready
Adaptive:
N/A

Props

Component props
Name
Type
Default
children
Required
<ReactElement>
-

Must be instances TableofContents.Item

accessibilityLabel
string
-

String that clients such as VoiceOver will read to describe the element. See accessibility section to learn more.

title
string
-

Title for the TableOfContents. See the title variant to learn more.

Usage guidelines

When to use
  • To make it easier to navigate a single page with a lot of content and sections
  • To navigate through a lengthy form that is broken down into sections
When not to use
  • When you need to navigate to new pages or links. Use SideNavigation
  • For pages that don’t have a lot of sections or content. Navigating via the browser or app scrollbar should be enough.

Best practices

Do

Position the TableOfContents 24–32px away from the main content. Top-align it with the content’s title.

Don't

Place the TableOfContents really far from the main content making it easy to miss, or hard to move efficiently between it and the content.

Do

Place the TableOfContents to the right of the main content on a LTR surface and to the left of the main content on an RTL surface.

Don't

Place the TableOfContents right next to the SideNavigation to differentiate it from link navigation.

Do

Use one TableOfContents per page.

Don't

Introduce unnecessary complexity by using more than one TableOfContents on a page.

Accessibility

The TableOfContents component is critical in navigating the structure of the application and thus has been assigned the 'navigation' role to improve its accessibility. This role ensures that the component is recognized as a 'landmark' by assistive technologies, such as screen readers. Be sure to include an accessibilityLabel for the screen reader for TableOfContents. Consider using meaningful labels to enhance the ease of navigation through the application.

Localization

Be sure to localize all text strings. Note that localization can lengthen text by 20 to 30 percent.

TableOfContents.Item depends on DefaultLabelProvider for internal text strings. Localize the texts via DefaultLabelProvider. Learn more
import { Box, DefaultLabelProvider, TableOfContents } from 'gestalt';

export default function Example() {
  const { hash } = window.location;

  return (
    <DefaultLabelProvider
      labels={{
        TableOfContents: {
          accessibilityLabel: 'Table of contents',
        },
      }}
    >
      <Box display="flex" justifyContent="center" padding={8}>
        <TableOfContents title="Beförderungen">
          <TableOfContents.Item
            active={hash === '#active-coupons'}
            href="#active-coupons"
            label="Aktive Gutscheine"
          />
          <TableOfContents.Item
            active={hash === '#active-credits'}
            href="#active-credits"
            label="Aktive Kredite"
          />
          <TableOfContents.Item
            active={hash === '#offer-codes'}
            href="#offer-codes"
            label="Angebot Codes"
          />
        </TableOfContents>
      </Box>
    </DefaultLabelProvider>
  );
}

Subcomponents

TableOfContents.Item

TableOfContents.Item is a subcomponent of TableOfContents. Use TableOfContents.Item to redirect the user to a different section of a page.

TableOfContents.Item Props

TableOfContents.Item subcomponent props
Name
Type
Default
active
Required
boolean
-

When set to true, it displays the item in "active" state.

href
Required
string
-

Directs users to the url when item is selected.

label
Required
string
-

Label for the item.

children
<ReactElement>
-

Must be instances TableofContents.Item

onClick
(arg1: {
  event: React.MouseEvent<HTMLAnchorElement> | React.KeyboardEvent<HTMLAnchorElement>;
  dangerouslyDisableOnNavigation: () => void;
}) => void
-

Callback when the user selects an item using the mouse or keyboard.

Variants

Nested directory

TableOfContents supports 5 levels of nesting. The first level maps to a section’s heading, which is usually an H2. The second level maps to a section’s subheading, which is usually an H3.

import { Box, TableOfContents } from 'gestalt';

export default function Example() {
  const { hash } = window.location;

  return (
    <Box display="flex" justifyContent="center" padding={8}>
      <TableOfContents title="Title">
        <TableOfContents.Item
          active={hash === '#level-1'}
          href="#level-1"
          label="Level 1"
        >
          <TableOfContents.Item
            active={hash === '#level-2'}
            href="#level-2"
            label="Level 2"
          >
            <TableOfContents.Item
              active={hash === '#level-3'}
              href="#level-3"
              label="Level 3"
            >
              <TableOfContents.Item
                active={hash === '#level-4'}
                href="#level-4"
                label="Level 4"
              >
                <TableOfContents.Item
                  active={hash === '#level-5'}
                  href="#level-5"
                  label="Level 5"
                />
              </TableOfContents.Item>
            </TableOfContents.Item>
          </TableOfContents.Item>
        </TableOfContents.Item>
      </TableOfContents>
    </Box>
  );
}

With title

A title can be added to TableofContents to be more clear about what is being navigated through.

import { Box, TableOfContents } from 'gestalt';

export default function Example() {
  const { hash } = window.location;

  return (
    <Box display="flex" justifyContent="center" padding={8}>
      <TableOfContents title="Promotions">
        <TableOfContents.Item
          active={hash === '#active-coupons'}
          href="#active-coupons"
          label="Active coupons"
        />
        <TableOfContents.Item
          active={hash === '#active-credits'}
          href="#active-credits"
          label="Active credits"
        />
        <TableOfContents.Item
          active={hash === '#offer-codes'}
          href="#offer-codes"
          label="Offer codes"
        />
      </TableOfContents>
    </Box>
  );
}

Writing

Items for a TableOfContents will be inherited from the headings on the page. For guidelines on writing headlines and titles, see our Content Standards

Component quality checklist

Component quality checklist
Quality item
Status
Status description
Figma Library
Ready
Component is available in Figma for web and mobile web.
Responsive Web
Ready
Component responds to changing viewport sizes in web and mobile web.

SideNavigation
SideNavigation is start-aligned and arranged vertically. It is used to navigate between page urls or sections when you have too many menu items to fit in horizontal Tabs.

Tabs
Tabs may be used navigate between multiple URLs. Tabs are intended as page-level navigation.

Edit page on GitHub