Back to Community
Home / Community / Plugin → Easy table of contents

Troubleshooting Easy Table of Contents Smooth Scroll Offset Issues

17 threads Sep 16, 2025 Plugin → Easy table of contents

Content

The 'Smooth Scroll Offset' feature in the Easy Table of Contents plugin is a popular way to account for fixed headers, ensuring that when a user clicks a link in the table of contents, the page scrolls to the correct position without the heading being hidden. However, based on community reports, this feature can sometimes malfunction or not work as expected. This guide will walk you through the most common reasons for these issues and how to resolve them.

Why Smooth Scroll Offset Problems Occur

Smooth scroll offset functionality relies on JavaScript to calculate the correct scroll position. Several factors can interfere with this process, including conflicts with other scripts, specific theme configurations, or caching. The most frequent causes identified by users are:

  • Plugin or Theme Conflicts: Other JavaScript from your theme or plugins can override or break the smooth scroll script.
  • Caching: Aggressive caching mechanisms may serve an old version of the JavaScript file that doesn't reflect your offset settings.
  • Special Characters in Headings: Headings containing commas (,) or other special characters can cause the generated anchor links to malfunction, breaking the smooth scroll.
  • Specific Theme Incompatibilities: Some themes, like Schema by MyThemeShop and Gorgo Theme, have been reported to have specific conflicts with this feature.
  • Cross-Page Links: The smooth scroll offset is designed to work on a single page. It will not function for links that point to a heading on a different page of a multi-page post.

Common Solutions to Try

1. Clear All Caches

This is one of the most common and simplest fixes. If you are using a caching plugin, a server-level cache, or a Content Delivery Network (CDN), clear all their caches. Additionally, clear your browser's cache and perform a hard reload (Ctrl+F5 on Windows or Cmd+Shift+R on Mac) to ensure you are loading the latest JavaScript files.

2. Check for JavaScript Errors

A fatal JavaScript error from another script can prevent the smooth scroll script from running entirely.

  1. Open the page with the table of contents in your browser (Chrome or Edge is recommended).
  2. Right-click on the page and select Inspect.
  3. Click on the Console tab.
  4. Look for any error messages shown in red. If you find any, try temporarily deactivating plugins or switching to a default WordPress theme to identify the source of the conflict.

3. Investigate Plugin and Theme Conflicts

To determine if a conflict is causing the issue, follow a standard troubleshooting process:

  1. Temporarily deactivate all other plugins except for Easy Table of Contents.
  2. If the smooth scroll offset starts working, reactivate your plugins one by one to identify the culprit.
  3. If the problem persists with all plugins deactivated, temporarily switch to a default WordPress theme like Twenty Twenty-One. If it works with the default theme, the issue is likely with your theme.

4. Avoid Special Characters in Headings

The plugin generates anchor IDs from heading text. Commas and other special characters can break these IDs. Where possible, avoid using commas in headings that will be included in the table of contents. The Easy Table of Contents team has been made aware of this issue through user feedback.

5. Understand the Limitations

It's important to understand that the smooth scroll feature has inherent limitations:

  • It cannot work for links that point to a heading on a different page (e.g., in a multi-page post). The offset is calculated and applied via JavaScript on the current page only.
  • It may not be compatible with all themes due to how they handle JavaScript or page layout.

6. Manual CSS Offset (If All Else Fails)

If you cannot resolve the JavaScript conflict and must disable smooth scrolling, you can use CSS to manually add padding to your headings. This method is less dynamic but can be effective.

Add the following CSS code to your theme's "Additional CSS" section or your child theme's style.css file. Adjust the 150px value to match the height of your header.

html {
    scroll-padding-top: 150px;
}

Note: This CSS method may not be as smooth as the JavaScript solution and browser support, while good, should be verified.

Conclusion

Smooth scroll offset issues are often rooted in conflicts or caching. By methodically working through the steps above—clearing cache, checking for errors, and testing for conflicts—you can usually identify and resolve the problem. For ongoing issues, the community around Easy Table of Contents is a valuable resource for finding workarounds and sharing solutions.

Related Support Threads Support