Navigation module

Table of Contents block

A list of the headings in your post that jumps to each section. Builds and updates itself, and highlights the section being read.

Overview

Table of Contents lists the headings of the post — WordPress Heading blocks and Brigade Heading blocks, including those inside synced patterns — as links. It updates as you edit. Headings without an HTML anchor get one automatically (a slug of their text, e.g. #getting-started), so nothing needs to be set up.

At a glance

Block name: wpbb/table-of-contents
Module: Navigation
Find it by searching: Table of Contents
Loads JavaScript on the site: Yes, a small script, only on pages that use this block

When and why to use it

Long articles, guides and documentation.
FAQ or policy pages with many sections.

Example scenarios

Long guide: under the introduction, levels H2–H3, Numbers, Tint, collapsible.
Docs sidebar: in a template sidebar, Plain list, highlight on.

How to add the Table of Contents block

Open the editor. In your WordPress dashboard go to Pages (or Posts) and click the page you want to edit, or click Add New. For headers, footers and templates, use Appearance → Editor (block themes).
Add a new block. Click the blue + (Block Inserter) button in the top-left corner, or the small + that appears where you want the block. You can also type / on an empty line.
Search for the block. Type Table of Contents in the search field. Brigade Blocks appear in the Brigade Blocks category and show the coral block icon.
Insert it. Click Table of Contents in the results. The block appears with a live list of the post’s headings.
Configure the content. Edit the text directly on the block, then open the Settings tab (gear icon) in the right-hand sidebar for the options described below. If the sidebar is hidden, click the gear icon in the top-right corner.
Customise the design. Switch to the Styles tab (half-filled circle icon) to change colours, spacing, borders and more — see Design & styling.
Save or publish. Click Save draft to keep working later, Preview to check it, or Publish / Update to make it live.

Content settings

You set up this block in two places: on the block itself in the editor, and in the Settings tab (gear icon) of the sidebar on the right. Every option is listed below, with its default value.

On the block (in the editor canvas)

Title

What it does: The heading above the list.
What to enter or choose: Text, or empty for “Contents”.
Default: Empty
How to use it: Click the text in the block on the page and type. Use the block toolbar for bold, italic and links.
When to use it: Optional.
Example: “On this page”.
Result: Also the list’s name for screen readers.

Settings panel: Contents

Highest heading level

What it does: The top level listed.
What to enter or choose: A number from 1 to 6.
Default: 2
How to use it: Drag the slider, or type a number in the box next to it.
When to use it: Usually 2 — H1 is the page title.
Example: 2 (H2).
Result: Headings above it are left out.

Deepest heading level

What it does: The lowest level listed.
What to enter or choose: A number from 1 to 6.
Default: 3
How to use it: Drag the slider, or type a number in the box next to it.
When to use it: Keep the list short: 3 is usually enough.
Example: 3 (H3).
Result: Deeper headings are left out; levels nest under their parents.

List

What it does: How items are marked.
What to enter or choose: One of: Numbers, Bullets, Plain.
Default: Numbers
How to use it: Click one of the buttons in the group.
When to use it: Always optional.
Example: Numbers.
Result: Numbers uses an ordered list.

Box

What it does: The box look.
What to enter or choose: One of: Tint, Card, Plain.
Default: Tint
How to use it: Click one of the buttons in the group.
When to use it: Always optional.
Example: Tint.
Result: Background and border change.

Settings panel: Behaviour

Show title

What it does: Shows the title above the list.
What to enter or choose: On or off.
Default: On
How to use it: Click the switch to turn it on (blue) or off.
When to use it: Always on when Collapsible (the title is the button).
Example: On.
Result: The title is hidden when off.

Collapsible

What it does: Lets visitors open and close the list by clicking the title.
What to enter or choose: On or off.
Default: Off
How to use it: Click the switch to turn it on (blue) or off.
When to use it: To save space.
Example: On for long lists.
Result: Uses a native, keyboard-accessible disclosure — no JavaScript.

Start collapsedShown when Collapsible is on

What it does: The list starts closed.
What to enter or choose: On or off.
Default: Off
How to use it: Click the switch to turn it on (blue) or off.
When to use it: Optional.
Example: Off.
Result: Visitors open it with the title.

Highlight the section being read

What it does: Marks the link of the section on screen as the visitor scrolls.
What to enter or choose: On or off.
Default: On
How to use it: Click the switch to turn it on (blue) or off.
When to use it: Useful in a sticky sidebar.
Example: On.
Result: The link turns coral and gets aria-current="location".

Design & styling

Select the block, open the Styles tab in the settings sidebar (the half-filled circle icon next to the gear) and use the three pickers at the top of the Style panel:

Element — which part of the block to style.
State — Normal, or a state such as Hover (only the states the part supports are offered).
Device — Desktop, Tablet or Mobile, for values that can differ per screen size.

Only panels that make sense for the chosen part and state are shown. The full meaning of every control is in the Styling Controls guide; below is exactly what Table of Contents offers.

Element: Links selected first

The links. Hover, Focus and Active (the highlighted section) states.

Styles-tab controls for “Links”
Panel	Control	Per device	Available in states
Typography	Font family	—	Normal
	Font size	Yes	Normal
	Weight	—	Normal
	Style	—	Normal
	Line height	Yes	Normal
	Letter spacing	Yes	Normal
	Letter case	—	Normal
	Alignment	Yes	Normal
	Decoration	—	Normal, Hover, Focus, Active
Colors	Text	—	Normal, Hover, Focus, Active

States for this part:

Hover — When the mouse pointer is over it. (Touch screens have no hover; they show the normal style.)
Focus — When it has keyboard focus — reached with the Tab key. Mouse clicks usually do not show focus styles.
Active — The selected / current item (.is-active).

Element: Block

The box.

Styles-tab controls for “Block”
Panel	Control	Per device	Available in states
Background	Type	—	Normal
	Color / Gradient	—	Normal
	Image	—	Normal
Border	Border type	—	Normal
	Border	—	Normal
	Radius	Yes	Normal
Box Shadow	Remove shadow	—	Normal
Box Shadow	Shadow layers	—	Normal
Spacing	Margin	Yes	Normal
Spacing	Padding	Yes	Normal
Sizing	Width	Yes	Normal
	Max width	Yes	Normal
	Height	Yes	Normal
	Min width / Min height / Max height	Yes	Normal
	Block alignment	Yes	Normal
Position	Position	Yes	Normal
	Top / Right / Bottom / Left	Yes	Normal
	Z-index	Yes	Normal
	Overflow	Yes	Normal
Transform	Move X / Move Y	—	Normal
	Scale X / Scale Y	—	Normal
	Rotate (°), Rotate X (°), Rotate Y (°)	—	Normal
	Skew X (°) / Skew Y (°)	—	Normal
Effects	Opacity (%)	Yes	Normal
	State transition (ms)	—	Normal
	Timing	—	Normal
Visibility	Show on Desktop / Tablet / Mobile	—	Normal

States: Normal only.

Element: Title

The title.

Styles-tab controls for “Title”
Panel	Control	Per device	Available in states
Typography	Font family	—	Normal
	Font size	Yes	Normal
	Weight	—	Normal
	Style	—	Normal
	Line height	Yes	Normal
	Letter spacing	Yes	Normal
	Letter case	—	Normal
	Alignment	Yes	Normal
	Decoration	—	Normal
Colors	Text	—	Normal

States: Normal only.

Responsive settings

Brigade Blocks uses three screen sizes: Desktop (wider than 1023px), Tablet (600–1023px) and Mobile (599px and narrower). Tablet and Mobile values are optional: when empty, the value of the next larger screen is used.

In the Styles tab, pick the Device first; these controls can then have a different value for that screen size: Font size, Line height, Letter spacing, Alignment, Radius, Margin, Padding, Width, Max width, Height, Min width / Min height / Max height, Block alignment, Position, Top / Right / Bottom / Left, Z-index, Overflow, Opacity (%).

The Visibility panel (Styles tab, Normal state) can hide the block entirely on Desktop, Tablet or Mobile.

Advanced options

HTML anchor (Advanced section of the Settings tab) — a unique name such as pricing, so you can link straight to this block with #pricing at the end of the page address (for example from a menu).
Additional CSS class(es) (Advanced section) — for custom CSS from your theme or the Site Editor. Separate several classes with spaces.
Custom attributes (Advanced section) — add data-*, title, aria-label, aria-describedby, lang or dir attributes. See Custom attributes.
State transition (Styles tab → Effects, Normal state) — how smoothly hover and focus styles animate.

How it works on your site

A <nav> with a nested list of links to the headings. Headings without an anchor get a matching id. A small script (only on pages with the block) highlights the current section and, when the block is in a template, links headings by their text.

Limitations and notes

Only Heading blocks are listed — not headings typed inside Custom HTML or other blocks.
Two headings with the same text get unique anchors (#faq, #faq-2).
Developers can change the list with the wpbb_toc_headings filter.

Troubleshooting

The list is empty on the site.

The post has no headings in the chosen levels. Check Highest and Deepest heading level.

Clicking a link scrolls the heading under my sticky header.

Add scroll-margin-top to headings in your theme, e.g. h2, h3 { scroll-margin-top: 100px; }.