WAIT: Table of Contents (ToC) scroll offset incorrect when using "Smooth Scroll (CSS)"

Bugs
1

Browser: Chrome 110
OS: macOS
URL: Not Public
Video: BorlabsScreenshot-2026-03-20-at-21-29-54

When the “Smooth Scroll (CSS)” option is enabled in Bricks settings, the scroll position for Table of Contents links is incorrect if a heading offset is defined.

Steps to reproduce:

  1. Go to Bricks settings and enable “Smooth Scroll (CSS)”
  2. Add a Table of Contents element
  3. Set “Headings offset (px)” to a value (e.g. 64)
  4. Click on any link in the Table of Contents

Expected behavior:

The page should scroll to the correct heading, taking the defined offset (e.g. 64px) into account.

Actual behavior:

The scroll position is incorrect and does not respect the configured heading offset.

Notes:

The issue appears to be related to how CSS-based smooth scrolling handles offset values. If “Smooth Scroll (CSS)” is disabled, it works as intended.

2

Hi Ben,
Thanks so much for your report!

The problem sounds similar to these:

Could you check if you have any relative wrappers that might affect the scrolling position (as described in the mentioned threads), or provide a link or login credentials (via email)?

Best regards,
timmse

3

The page uses a <header> with position:sticky, <main> and <footer> with position:relative.

I tested removing position:sticky from the header and changing position:relative to position:static on both and via the browser’s developer tools. However, the issue still persists, so it does not seem to be directly caused by these positioning rules.

This behavior is consistent with the issue observed on the following page: Terms Of Service ( DUPLICATE: "Smooth scroll (CSS)" setting enabled causing inconsistent scrolling with Tabs (nestable) and Table of contents elements )

While investigating, I came across a potentially related issue in the tocbot ( Tocbot ) documentation:

// CAUTION: Doesn’t work well of you already have scroll-behavior set to smooth globally in your CSS - see Flash when scrolling / doesn't scroll to right spot · Issue #273 · tscanlin/tocbot · GitHub
scrollSmooth: true,

4

That’s a great tip! Please add the following CSS to Bricks » Settings » Custom Code » Custom CSS or to Theme Styles » Stylesheet:

html:has([data-smooth-scroll="1"]) {
  scroll-behavior: auto;
}

This checks whether a data-smooth-scroll="1" attribute exists anywhere in the HTML (it does—in the toc element) and, if so, resets the CSS smooth scroll to auto to prevent it from conflicting with the toc JavaScript smooth scroll.

2 Likes
WIP: Table of contents Element: Highlighting does not work with position: relative
5

What a great start to the week! This works perfectly, thank you so much.

1 Like
6

That’s right, it couldn’t go much better :smiley:
I’m really glad the solution works. I’ll suggest this in the other thread(s) as well—as far as I can see, there’s no reason not to implement it natively.

7

Hi timmse,

actually my post was regarding another problem, namely the highlighting of the ToC links. The state class »is-active-li« doesn’t get assigned if the container element of the targeted Headline is set to position:relative. Please check if you can reproduce this behavior.

The scrolling position of the content is working fine in my case.

Kind regards,
Benjamin

8

Hi @benjamin,
I know what your report was (and still is) about, and Matej confirmed it back then—but it doesn’t hurt to ask, since the problem could be related.

But if that’s not the case: no problem :slight_smile: I’m sorry we haven’t been able to resolve your issue yet.

1 Like