WordPress TOC Plugin Causing CLS Errors

Have you heard of "Web Vitals Obsession"? It's not a soft drink — it's the obsession triggered by Google after introducing these metrics it deems essential for good search rankings.

One of these metrics is CLS (Cumulative Layout Shift), something like "movement of the content distribution". We can translate it as: "whether elements on the page shift before settling into their final position after loading".

For such an important metric, I was surprised to find that WordPress TOC plugins are causing so many problems with this metric.

Why do "Table Of Content" (TOC) plugins cause CLS errors?

Typically, CLS errors in this type of WordPress plugin appear when, at the start, we want the box to appear collapsed. The problem is that this "box" is simply a div containing a list inside (<ul>).

When we enable the option for it to appear collapsed on load, what we're actually doing is using JavaScript to hide the list after the full page has loaded.

So at the start of loading it will appear open, and when the box closes, there will be a jump of the elements placed below the TOC list. There are two factors that directly influence the CLS value:

1. The size of the table of contents or TOC index: The more headings appear in the list, the greater its vertical proportion. This means that when it closes, there will be a greater shift of the elements below.
2. Where we position the TOC list: This is a decisive factor. We usually want this list to appear at the beginning of the article as an index. This position will cause all page elements to shift during the jump mentioned above.

Due to the large number of incompatibilities and loading issues that ready-made plugins tend to cause, WebHeroe always recommends using custom plugins.

Which TOC plugins are causing CLS problems?

There are many TOC plugins — even some WordPress page builders have a built-in TOC. But I've been able to find errors of this type in easyTOC (Easy Table Of Contents) and Table Of Content Plus (TOC Plus), although I'm sure they're not the only ones.

This is because almost all plugins of this type use JavaScript when we want them to appear collapsed on page load.

Below I'll leave you with the quick and simple solutions for the plugins mentioned, although these are not the recommendations I personally advise. Further down you'll discover a much more effective solution.

Fix CLS in EasyTOC

This issue has been a frequent topic of discussion among EasyTOC users. The solution they've decided to provide in this thread is somewhat peculiar, as they ask you to modify a plugin file.

Honestly, I don't recommend that solution, especially because once the plugin is updated we'll face the same error again. Instead, we could place this CSS code in Appearance/Customize/Additional CSS or in the stylesheet of our active theme:

ul.ez-toc-list.ez-toc-list-level-1 {
  display: none;
}

Fix CLS in Table Of Content Plus

In this case, to force the TOC list to be closed before it's even rendered, we can include the following CSS code in Appearance/Customize/Additional CSS or in the stylesheet of our active theme:

.toc_list {
  display: none;
}

If you want to learn more about how to create attractive and functional websites in WordPress, I recommend reading our article on the best WordPress visual page builders. There you'll find a detailed comparison of the most popular options for designing your site without needing to code.