[Feature Request]: Add anchor scroll support inside overflowing elements

[hirasso]

Describe the problem 🧐

• Currently, scroll plugin only supports scrolling the Window
• The underlying library gmrchk/scrl has that limitation as well
• More complex scenarios like overlays or other overflowing divs are currently not supported

Describe the propsed solution 😎

• Fork gmrchk/scrl to swup/scrl OR implement the logic directly in ScrollPlugin
• Implement support for scrolling to anchor elements inside overflowing divs
• Pass the scroll root to swup.scrollTo()

Example implementation

/**
 * Find the closest overflowing parent
 */
export function getScrollableParent(
  element: Element | null | undefined,
): HTMLElement | null {
  if (!element) return null;

  let parent: HTMLElement | null = element.parentElement;

  while (parent) {
    const { overflowY } = getComputedStyle(parent);
    const isScrollable =
      ["auto", "scroll"].includes(overflowY) &&
      parent.scrollHeight > parent.clientHeight;

    if (isScrollable) {
      return parent;
    }

    parent = parent.parentElement;
  }

  return document.documentElement;
}
/**
 * Attempt to scroll to an anchor, inside an overflowing element or the Window
 */
export function maybeScrollToAnchor(
  swup: Swup,
  hash?: string,
  animate: boolean = false,
): boolean {
  if (!hash) {
    return false;
  }
  const scrollPlugin = swup.findPlugin("SwupScrollPlugin") as SwupScrollPlugin;
  const element = scrollPlugin.getAnchorElement(hash);

  if (!element) {
    console.warn(`Anchor target ${hash} not found`);
    return false;
  }

  if (!(element instanceof Element)) {
    console.warn(`Anchor target ${hash} is not a DOM node`);
    return false;
  }

  const { top: elementTop } = element.getBoundingClientRect();
  const scrollRoot = getScrollableParent(element)!;
  const scrollTop = scrollRoot.scrollTop;

  const y = elementTop + scrollTop - scrollPlugin.getOffset(element);
  // swup.scrollTo(scrollRoot, y, animate);
  scrollToAnchor(swup, scrollRoot, y, animate);

  return true;
}

/**
 * Scroll to an anchor inside an element
 */
export function scrollToAnchor(
  swup: Swup,
  target: HTMLElement,
  y: number,
  animate: boolean,
): void {
  if (!animate) {
    swup.hooks.callSync("scroll:start", undefined);
    target.scrollTo(0, y);
    swup.hooks.callSync("scroll:end", undefined);
    return;
  }

  /**
   * Use GSAP ScrollToPlugin for animated scrolling
   * @see https://greensock.com/docs/v3/Plugins/ScrollToPlugin
   */
  gsap.to(target, {
    duration: 0.6,
    scrollTo: {
      y,
      autoKill: !isTouch(),
    },
    ease: "scrl1",
    onStart: () => {
      swup.hooks.callSync("scroll:start", undefined);
    },
    onComplete: () => {
      swup.hooks.callSync("scroll:end", undefined);
    },
    onAutoKill: () => {
      swup.hooks.callSync("scroll:end", undefined);
    },
  });
}

Alternatives considered 🤔

Keep hacking this in every new project.

Considerations

This would be a breaking change since swup.scrollTo() would now need to know what to scroll (The Window or an element).

How important is this feature to you? 🧭

Would make my life a lot easier

Checked all these? 📚

• I have read and searched the official docs
• I have checked discussions and existing issues for related problems
• I agree to follow this project's Code of Conduct
• I have provided all necessary information to the best of my knowledge

[hirasso]

Actually – now that GSAP is free, how about we drop the scrl dependency altogether and use gsap/ScrollToPlugin instead? That would save us a lot of work.

We could then even make the ease and duration configurable:

new SwupScrollPlugin({
  ease: "power4.out",
  duration: 0.15
});

EDIT: Probably not a good idea, since it will increase bundle size considerably

[hirasso]

...looks like gmrchk/scrl isn't fit for this use case, either. It creates one instance that scrolls the window. And it depends on it being one instance. So not a good fit for scrolling (changing) overflowing divs...

Maybe it's simplest to keep this in userland. What do you think @daun ?

[daun]

Makes sense to support this! Especially since we've been meaning to support remembering scroll positions per container in the history entries, so restoring those would require this feature too.

How big is the GSAP plugin? And would it require GSAP core as well?

I'm also not against forking scrl into the swup org and making the adjustments there if we see a path to getting it done easily.

[hirasso]

GSAP's ScrollToPlugin requires GSAP core. I've forked sclr to swup/scrl. Maybe it is feasable to enhance it to support various scroll containers.

Alternatively, we could completely remove scrl and use native scrollTo() with behavior: "smooth" and let users enhance it if they want. That would

• decrease the bundle size of ScrollPlugin
• decrease the complexity we have to deal with (scrl doesn't have any tests, yet)
• be not as snappy as scrl but a more robust solution

[daun]

The problem with native scrolling is the lack of an offset option. In most recent projects it was necessary to specify the header height to make sure focussed elements show up in the right spot :( We could bundle something like zenscroll that already supports different scroll containers and custom offsets. It's not unit-tested, but certainly battle-tested. Or adjust scrl to fit our requirements. Might be simpler.

[hirasso]

scrollIntoView doesn't support an offset. But we could easily add offset support by wrapping scrollTo. I'll provide an example of what I mean.

[hirasso]

I've tried my luck in #88 and I'm amazed how simple and easy it was! Looking forward to hearing what you think :)