Table of Contents (TOC) Block - Fast & SEO Friendly
Automatically generate a clean, nested table of contents from your headings - with zero frontend JavaScript by default.
Quick Start
You can have a table of contents live on a post in under a minute.
- Open a post or page in the block editor and place the cursor where the TOC should appear - usually right before the first heading.
- Type
/toc(or open the block inserter and search for Table of Contents) and insert the block. - The block instantly scans every heading in the post - including headings inside Groups, Columns, and reusable blocks - and shows a live preview.
- With the block selected, open the Settings sidebar to adjust which heading levels are included, the list style, and any extras you need.
- Save the post and view it in a browser. Each TOC entry is an anchor link that jumps straight to its section.
Content
The first panel in the block sidebar controls what appears in the TOC.
| Setting | Default | Description |
|---|---|---|
| Custom Title | Empty | Replaces the default "Table of Contents" title with your own text (e.g. "What's Inside", "Quick Navigation"). Leave empty to keep the default. |
| Hide TOC Title | Off | Removes the built-in title entirely. Useful if you prefer to add your own Heading block above the TOC for full control over the heading level and styling. |
| Minimum Level | H2 | Start the TOC from this heading level. Set it to H3 to skip your H2 headings, for example. |
| Maximum Level | H6 | Stop including headings deeper than this level. Set it to H3 to show only H2 and H3 headings and keep the TOC short. The sidebar warns you if the minimum is set deeper than the maximum (that combination produces an empty TOC). |
| Minimum headings to show TOC | 1 | Hide the TOC automatically when the post has fewer qualifying headings than this number (range 1-10). Only headings that would actually appear in the TOC are counted - excluded and out-of-range headings don't count. Great for keeping short posts clean. |
| Show heading count | Off | Displays the number of visible headings as a badge next to the TOC title (e.g. "8 headings"). Has no effect when the title is hidden. |
| Exclude headings | Empty | Comma-separated keywords. Any heading whose text contains one of these words (case-insensitive) is hidden from the TOC and skipped by per-section back-to-top links. Example: conclusion, faq. |
Display
Control how the TOC looks and whether readers can collapse it.
| Setting | Default | Description |
|---|---|---|
| Style | Default |
Default - a plain list that inherits your theme's styling. Boxed - wraps the TOC in a subtle bordered box with padding, so it stands out from the article without any custom CSS. |
| Collapsible | Off | Adds a toggle button next to the title so readers can show or hide the TOC list with one click. The toggle is keyboard-accessible with a visible focus ring. |
| Collapsed by default | Off | Only visible when Collapsible is on. Starts with the list hidden until the reader expands it. Readers without JavaScript still see the full list. |
| List style | Bulleted |
Bulleted - a standard unordered list. Numbered - an ordered list; each nesting level restarts at 1. Hierarchical (1.1, 1.1.1) - prefixes each entry with numbers reflecting the heading structure, like a book outline. |
| Flat list (no indent) | Off | Removes bullet points and first-level indentation for a tidy, compact look - especially with deeply nested headings. |
Links & Behavior
Fine-tune how the anchor links behave and add optional navigation extras.
| Setting | Default | Description |
|---|---|---|
| Show "Back to top" link | Off | Adds a link below the TOC list that scrolls the reader back to the top of the page. Works even with JavaScript disabled. |
| Add per-section back to top links | Off | Inserts a "Back to top" link after every heading in the post content, so readers can return to the TOC from anywhere in a long article. Excluded and hidden headings are skipped. |
| Copy link button on hover | Off | Shows a small button beside each TOC item that copies a direct link to that section to the clipboard - handy for sharing deep links to a specific part of the article. |
| Enable smooth scrolling | Off | Jumps to sections glide smoothly instead of snapping instantly. Implemented with pure CSS (scroll-behavior: smooth) - no JavaScript is added. |
| Scroll offset (px) | 0 | Leaves this much space above a heading when jumping to it from the TOC (range 0-300). Set it to roughly the height of your sticky/fixed header so headings land below the header instead of hiding behind it. Pure CSS (scroll-margin-top). |
| Hide TOC from search snippets | Off | Adds the data-nosnippet attribute to the TOC so search engines don't use the list of headings as your search result snippet text. |
| Use absolute URLs | Off | Builds each anchor link with the full page URL (https://example.com/post/#section) instead of just #section. Useful when the content is republished elsewhere or shared via RSS. |
Colors & Alignment
The block uses native Gutenberg styling, so the standard editor tools work directly on it.
Background & text color
Set both from the block sidebar's Color panel - no Group wrapper needed. Combine with the Boxed style for a highlighted TOC card.
Wide & full width
The block supports the theme's Wide and Full alignment options from the block toolbar.
Padding & borders
For extra spacing or a custom border, wrap the TOC in a Group block and use the Group's native dimension and border controls.
Theme-friendly
The TOC ships with safe default list spacing and otherwise inherits your theme's typography, so it looks native everywhere - including RTL languages.
Auto-Insert
Show a table of contents on every post automatically - without adding the block to each one. Configure it under WPWing > TOC Block in the WordPress admin.
| Setting | Default | Description |
|---|---|---|
| Enable for post types | None | Check the post types (Posts, Pages, public custom post types) that should get an automatic TOC. Leaving every box unchecked turns auto-insert off. |
| Position | Before the first heading | Where the automatic TOC is placed: Before the first heading, After the first paragraph, or Top of the content. |
| Minimum headings | 2 | Posts with fewer qualifying headings are skipped, so short posts stay clean. |
Excluding Headings
There are three independent ways to keep a heading out of the TOC. All of them also exempt the heading from per-section back-to-top links.
1. By level range
Use Minimum Level and Maximum Level in the Content panel to include only a slice of your heading hierarchy - for example H2 and H3 only.
2. By keyword
Type comma-separated words in the Exclude headings field. Any heading containing one of them is hidden. This is the quickest way to drop recurring sections like "Conclusion" or "References" across a site.
3. Per heading, with a CSS class
- Select the heading block you want to hide from the TOC.
- Open the Advanced panel in the block sidebar.
- Add
wpwing-toc-hiddento the Additional CSS class(es) field.
The heading still renders normally in the post; it is simply skipped when the TOC is generated. It works alongside other classes (e.g. a font-size class) without conflict.
Heading Anchors
Every heading that appears in the TOC receives a URL-safe anchor ID generated from its text. The same ID is used in the TOC link and on the heading itself, so they always match.
Custom anchors respected
If you set your own anchor on a heading via Advanced > HTML anchor, the TOC links to it instead of generating one - existing incoming links keep working.
Duplicate headings
Two headings with the same text get unique anchors (setup, setup-2, ...), so every TOC link jumps to the correct section.
Any language
Accented characters, non-Latin scripts (e.g. Bangla), and emoji in headings are handled safely - the text renders untouched and the anchor is URL-encoded.
Nested content
Headings inside Groups, Columns, and reusable blocks are found, anchored, and listed just like top-level headings.
Recipes
Common setups and how to configure them.
TOC that plays nicely with a sticky header
Stop headings from landing hidden behind your fixed navigation bar when readers click a TOC link.
- Measure your sticky header's height (right-click it, choose Inspect, and read the height in DevTools) - say it's 80 px.
- Select the TOC block and open the Links & Behavior panel.
- Set Scroll offset (px) to
80(a few px more adds breathing room). - Optionally enable Enable smooth scrolling for glide-style jumps.
Compact collapsed TOC for long tutorials
A boxed table of contents that starts closed, so it never pushes the intro below the fold.
- In the Display panel, set Style to Boxed.
- Enable Collapsible, then enable Collapsed by default.
- In the Content panel, enable Show heading count so readers see how many sections await before expanding.
- Set Maximum Level to H3 to keep the expanded list scannable.
Automatic TOC across the whole blog
Every post gets a table of contents - no editing required, short posts stay clean.
- Go to WPWing > TOC Block in the admin.
- Check Posts under "Enable for post types".
- Set Position to Before the first heading.
- Set Minimum headings to
3so brief updates and announcements are skipped. - For any special post that needs different TOC settings, just add the block manually there - it overrides the automatic one.
Shareable deep links to every section
Let readers grab a direct URL to any part of a long reference article.
- In Links & Behavior, enable Copy link button on hover.
- Enable Add per-section back to top links so readers can hop back after following a shared link.
- If the article is republished elsewhere, also enable Use absolute URLs.
For Developers
Useful hooks and markup details for theme and plugin authors.
Markup
The TOC renders as a semantic <nav class="wpwing-toc"> element with an aria-label, containing a <ul> or <ol> with the class wpwing-toc-list. The Boxed style adds wpwing-toc--boxed; collapsible mode adds wpwing-toc--collapsible. Target these classes from your theme's stylesheet for custom styling.
Performance
No JavaScript or CSS files are enqueued on the frontend beyond the block's own stylesheet. Smooth scrolling and scroll offset are inline CSS. Only the collapsible toggle, back-to-top links, and copy-link buttons print a few lines of inline script in the footer - and only when enabled.
SEO integrations
The block registers itself as a table of contents with Rank Math (via the rank_math/researches/toc_plugins filter) and Yoast SEO (via wpseo_table_of_contents_blocks), so both plugins' content analysis recognizes it.
FAQ
How do I change the default "Table of Contents" text?
Select the block and type your own text in the Custom Title field in the Content panel. Alternatively, toggle Hide TOC Title on and add a standard Heading block right above the TOC for full control over its level and styling.
How can I add a background color or border to the block?
Background and text color are available directly in the block sidebar's Color panel. For a quick pre-styled look, set Style to Boxed in the Display panel. For custom paddings and borders, wrap the TOC in a Group block and use the Group's native controls.
How do I exclude a specific heading from the TOC?
Select that heading block, open its Advanced panel, and add wpwing-toc-hidden to Additional CSS class(es). To exclude headings in bulk by their text, use the Exclude headings keyword field on the TOC block instead. See Excluding Headings.
Does this plugin add extra scripts or bloat to my site?
No. The plugin generates lightweight, valid, semantic HTML and never loads external JavaScript files. If you enable an interactive option (collapsible toggle, back-to-top, or copy-link buttons), a few lines of inline script are printed in the footer - nothing else. With those options off, the frontend is 100% JavaScript-free.
My sticky header covers the heading when I click a TOC link. How do I fix it?
Open the Links & Behavior panel and set Scroll offset (px) to roughly the height of your sticky header. Headings will then land below the header instead of behind it. This is done with pure CSS - no JavaScript is added.
Can the TOC appear automatically without adding the block to every post?
Yes. Go to WPWing > TOC Block, check the post types you want, and pick a position. The automatic TOC uses the same fast renderer as the block, skips posts below your minimum-headings threshold, and steps aside on any post where you place the block manually. See Auto-Insert.
I set a custom HTML anchor on a heading - will the TOC use it?
Yes. If you give a heading your own anchor via its Advanced > HTML anchor field, the TOC links to that anchor instead of generating one, so your existing incoming links keep working.
Why doesn't the TOC show up on my post?
The most common causes: the post has fewer qualifying headings than your Minimum headings to show TOC value; every heading falls outside the selected Minimum/Maximum Level range; or all headings are excluded by keyword or the wpwing-toc-hidden class. In the editor, the block shows a notice explaining which condition is hiding it.
Does it work with paginated (multi-page) posts?
Yes. If you split a post with the Page Break block, TOC entries for headings on other pages link to the correct page automatically, including on sites using plain permalinks. With auto-insert, the TOC appears on the first page only.