Component: Table of Contents in Oxygen

This component allows you to add a collapsible table of contents to your templates with support for sticky positioning, counters, icons, and lots of style options for creating different variations of tables of contents both inline and sticky/fixed.

How to Get Started

When you first add the Table of Contents to the page, the first thing to do is add your content selector. This is the class or ID on the page that contains the content you’re wishing to build the table of contents for. Once you’ve added this selector, you can then click ‘apply params’ and the Table of Contents will be built based on the content it finds on the page inside that container and you can then style and adjust your settings from there.

Note – the headings, if inside gutenberg for eg, may not automatically have their own IDs which is needed. If so, instead of manually adding IDs to every heading, you can go to Behaviour > Add unique IDs to headings and enable. This will dynamically add unique IDs to any headings that are found inside your container without an ID.

Primary Controls

Content selector – Neccessary to get started. Make sure you add a class to your post content and then add as a selector and click ‘apply params’ to allow the Table of Content to be built dynamically. Be sure that you’re previewing a page where there is some content with headings.

Heading Selectors – You may not want to include a link to every header, you can narrow down the tags you want to be included. Default is h2,h3,h4.h5

Initial Collapse Depth – This controls how many levels of headings are collapsed by default. If you’re creating an inline table of contents, it’s best to set this to 0 to make sure none of the headings are collapsed. If you’re using sticky or fixed positioning and have a lot of content, it would be better to collapse some of them initially so they only reveal as you scroll past those headings.

Ignore Selector – Some headings you may wish to not include, even though they share a tag with others that you do wish to include. You can add a class to these headings, for eg ‘ignore’ and then use that selector here. Only the headings found with this class will be not included.

Icons / Counters / Borders

The three main layout types are to include counters, icons or borders. The border makes sense for either sticky or fixed positioned table of contents as the border will select on the currently active.

Behaviour

Smooth scroll – Enable to ensure the browser will scroll smoothly to the headings when each link is clicked, supports scroll offset (in px, should be set w/o entering a unit) to make the browser account for stick headings. Note that if you’re already using a global smooth scroll, such as from Oxygen’s global settings, make sure the offset is set in the global setting also.

Add unique IDs to headings – The content needs IDs on the headings in order to function. With Oxygen elements this will always be the case, but if you’re using content from Gutenberg for eg, you will want to enable this setting to make sure each heading is given it’s own unique ID.

Note

It’s recommended to stick to only using one Table of Contents component per page. It is possible to use multiple, but the active style CSS will only be applied to the very last version of the component on the page. For inline TOCs this won’t be a problem, but you’d want to avoid setting up multiple sticky TOCs if you want the styles to change as the user scrolls.