scrollToElement does not work at all (or as I expect it to work)

[icedemon72]

When I try to use your new scrollToElement hook, I am getting only redirected to page (it seems to activate goToPage(x) only). Also I have really heavy logic with various selectors and stuff to do scrollToElement function, so it would save me lots of work if this was implemented natively (plus currently I need scrollToElement with centering the element in view logic).

Maybe I am doing something wrong but my solution sometimes redirects me to page 1 even though (for example) page 17 exists where my element (created using updateElement) is.

const scrollToRestriction = useCallback(
  async (key: string, pageHint: number) => {
    if (pageHint) goToPage(pageHint);

    await waitForPageRendered(pageHint);

    const el = restrictionRefs.current[key];
    if (!el) return;

    const pagesRoot = getPagesRoot();
    if (!pagesRoot) return;
    const container = getScrollableDescendant(pagesRoot) ?? pagesRoot;

    centerUntilSettled(container as HTMLElement, el, {
      tolerance: 8,
      stableFrames: 2,
      timeoutMs: 800,
      animDuration: 520
    });
  },
  [goToPage]
);

P.S. Perhaps we need access to the scrollable container inside the document? I currently retrieve it using this helper:

export function getScrollableDescendant(root: HTMLElement): HTMLElement | null {
  const isScrollable = (node: Element) => {
    const st = getComputedStyle(node as HTMLElement);
    return (
      /(auto|scroll)/.test(st.overflowY) && (node as HTMLElement).scrollHeight > (node as HTMLElement).clientHeight
    );
  };
  if (isScrollable(root)) return root;
  const q: Element[] = Array.from(root.children);
  while (q.length) {
    const node = q.shift()!;
    if (isScrollable(node)) return node as HTMLElement;
    q.push(...Array.from(node.children));
  }
  return null;
}

[icedemon72]

As you can see I am on page 13 but it scrolled me to the first page

[david-reactpdf]

@icedemon72

Thanks for raising this, we’re currently investigating the issue and will update you once we have more details.

[david-reactpdf]

@icedemon72

After reviewing your implementation, it looks like the code you shared is a partial custom setup that manually calls goToPage and handles scrolling. Since your current logic is quite customized, it’s possible that some parts may be interfering with React PDF’s scrollToElement behavior.

We’ve tested the scrollToElement hook (JSX/TSX) on v1.12.0 using the example in our docs, and it appears to be working correctly on our end: React PDF Documentation – scrollToElement

To help us pinpoint what’s going wrong in your case, would you be able to share a minimal reproducible example where scrollToElement fails or the exact code where scrollToElement is not expected? That would really help us investigate and reproduce the issue. If you prefer not to post the code publicly here, feel free to email it to support@react-pdf.dev.

[icedemon72]

@david-reactpdf
My current implementation doesnt use scrollToElement because when I started this project back in October, that API didnt exist yet, so I had to implement the scrolling logic manually. Now that scrollToElement is available in the context, I tried switching to it - but I’m running into issues when dealing with a large number of elements across many pages.

In my project, I have over 100 “boxes,” each containing multiple “highlights,” which are essentially simulated text highlight areas. The challenge is scrolling precisely to a specific element that’s located many pages away. Because those pages are not rendered in the DOM until they are scrolled into view, scrollToElement doesnt seem to reliably find or render the target element before attempting to scroll to it.

The examples in the documentation only cover a single element at the top of the page, so they don’t reflect the complexity of having 100+ elements spread across 100+ pages. It would be incredibly helpful if you could test (or provide guidance on) how scrollToElement behaves in scenarios with many pages and many elements, especially when the target element hasnt been rendered yet.

I will test this once more locally, will make sure to comment again once I do.

Thank you.

P.S. now I am seeing this page which will help me tremendously... thanks :)

[david-reactpdf]

@icedemon72

Thanks for the detailed context. We’ll definitely take this into account and look forward to hearing your results after testing locally. Let us know how it goes!

[icedemon72]

@david-reactpdf Thank you again for your reply, I am sorry because I did not to come back with the update. I have tested it today too, and it seems not to work. I will be emailing you the video with a simple demo, no matter what I do it wont work. Here is the code I am using (NOTE: I have tweaked it a bit in order to remove unnecessary stuff not related to scrollToElement API, my original code (without a custom scroll logic) is slightly different)

Scrolling to the element

useEffect(() => {
  if (!activeRestrictionId) return;

  const restriction = restrictions.find(r => r.id === activeRestrictionId);
  if (!restriction) return;

  const first = restriction.data[0];
  const key = `${first.page}-${activeRestrictionId}-0`;

  scrollToRestriction(key, first.page, activeRestrictionId);

  const selector = `[data-restriction-id="${activeRestrictionId}"][data-highlight="true"]`;
  const elements = document.querySelectorAll<HTMLElement>(selector);

  setTimeout(() => setActiveRestrictionId?.(null), 100);

  if (elements.length > 0) {
    elements.forEach(el => el.classList.add('active'));

    const timer = setTimeout(() => {
      elements.forEach(el => el.classList.remove('active'));
    }, 2500);

    return () => clearTimeout(timer);
  }
}, [activeRestrictionId, restrictions, scrollToRestriction, setActiveRestrictionId]);

const scrollToRestriction = useCallback(
  (key: string, page: number, targetId?: EntityId) => {
    const index = elementIndexMap.current[key];
    if (index == null) return;

    console.log('PAGE: ', page, 'INDEX: ', index);

    scrollToElement(page, index, { behavior: 'smooth' });

    if (targetId && setScrolledToId) {
      setScrolledToId(targetId);
    }
  },
  [scrollToElement, setScrolledToId]
);

Generating elements

 useEffect(() => {
  restrictions.forEach((restriction, restrictionIndex) => {
    const restrictionId = restriction.id;

    restriction.data.forEach((coordinate, coordIndex) => {
      const baseKey = `${coordinate.page}-${restrictionId}-${coordIndex}`;

      updateElement(coordinate.page, (prev = [], _dim, _rot, scale) => {
        const isInView = Math.abs(coordinate.page - focusedPage) <= HIGHLIGHTS_IN_VIEW_PAGES;

        const filteredPrev = prev.filter(el => {
          const key = (el as any).key;
          return typeof key !== 'string' || !key.startsWith(baseKey);
        });

        const elements: JSX.Element[] = [];

        elements.push(
          <RectBox
            key={baseKey}
            restrictionId={restriction.id}
            ref={(el: HTMLDivElement | null) => {
              restrictionRefs.current[baseKey] = el;
              boxRefs.current[baseKey] = el;
            }}
            rect={coordinate.area!}
            scale={scale / 100}
            onHoverChange={(id, hovering) => setHoveredRestrictionId(hovering ? id : null)}
            onClick={() => {
              handleRestrictionClick(restrictionId);
              const el = restrictionRefs.current[baseKey];
              if (!el) return;
              const pagesRoot = getPagesRoot();
              if (!pagesRoot) return;
              const container = getScrollableDescendant(pagesRoot) ?? pagesRoot;
              centerUntilSettled(container as HTMLElement, el);
            }}
          />
        );

        if (isInView) {
          coordinate.textRows?.forEach((textLineRect, index) => {
            const textLineKey = `${baseKey}-textLine-${index}`;
            elements.push(
              <RectHighlight
                key={textLineKey}
                ref={(el: HTMLDivElement | null) => {
                  restrictionRefs.current[textLineKey] = el;
                }}
                rect={{ ...textLineRect, page: coordinate.page }}
                scale={scale / 100}
                restrictionId={restriction.id}
              />
            );
          });
        }

        const final = [...filteredPrev, ...elements];

        final.forEach((el, idx) => {
          const key = (el as any).key;
          if (typeof key === 'string') {
            elementIndexMap.current[key] = idx;
          }
        });

        return final;
      });
    });
  });

  return () => {
    allPages.forEach(p => clearElements(p));
  };
}, [restrictions, updateElement, clearElements, handleRestrictionClick, allPages, focusedPage]);

I am always rendering RectBox element which should be scrolled to, RectHighlights are only highlighted text lines, and they are irrelevant to the scrolling logic

P.S. I have tested it even without useEffect logic but with only scrollToElement and I get the same results...

 <RectBox
  key={baseKey}
  restrictionId={restriction.id}
  ref={(el: HTMLDivElement | null) => {
    restrictionRefs.current[baseKey] = el;
    boxRefs.current[baseKey] = el;
  }}
  rect={coordinate.area!}
  scale={scale / 100}
  onHoverChange={(id, hovering) => setHoveredRestrictionId(hovering ? id : null)}
  onClick={() => {
    // handleRestrictionClick(restrictionId);

    const index = elementIndexMap.current[baseKey];
    if (index == null) return;

    scrollToElement(coordinate.page, index, { behavior: 'smooth' });
  }}
/>

[david-reactpdf]

@icedemon72

Thanks for taking the time to write this up and for sharing the detailed code snippets. I really appreciate the effort, this is very helpful for us to understand what’s going on.

You mentioned you were going to email me a video showing a minimal demo where this doesn’t work. I just wanted to check whether you’ve managed to send that through yet. Having the video will really help us correlate the runtime behavior with the code and narrow down where things might be going wrong.

Looking forward to it, and thanks again for your patience.

[icedemon72]

@david-reactpdf

Hello David, yeah I've managed to do so, maybe the mail went into spam? Datetime is 24.11.2025 10:06 in case you have to find it by the date.
Cheers!