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
Props
Usage guidelines
- 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 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
Position the TableOfContents 24–32px away from the main content. Top-align it with the content’s title.
Place the TableOfContents really far from the main content making it easy to miss, or hard to move efficiently between it and the content.
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.
Place the TableOfContents right next to the SideNavigation to differentiate it from link navigation.
Use one TableOfContents per page.
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.
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
Localization
Be sure to localize text and accessibilityLabel
. Note that localization can lengthen text by 20 to 30 percent.
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 padding={8} display="flex" justifyContent="center"> <TableOfContents title="Title"> <TableOfContents.Item label="Level 1" href="#level-1" active={hash === '#level-1'} > <TableOfContents.Item label="Level 2" href="#level-2" active={hash === '#level-2'} > <TableOfContents.Item label="Level 3" href="#level-3" active={hash === '#level-3'} > <TableOfContents.Item label="Level 4" href="#level-4" active={hash === '#level-4'} > <TableOfContents.Item label="Level 5" href="#level-5" active={hash === '#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 padding={8} display="flex" justifyContent="center"> <TableOfContents title="Promotions"> <TableOfContents.Item label="Active coupons" href="#active-coupons" active={hash === '#active-coupons'} /> <TableOfContents.Item label="Active credits" href="#active-credits" active={hash === '#active-credits'} /> <TableOfContents.Item label="Offer codes" href="#offer-codes" active={hash === '#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
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. |
Related
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.