[New Scrollbars]: Vertical scrolling not applied when ShadowDOM content grows

[siarheiyelin]

UUI 6.3.3

Steps to Reproduce

1. Open https://uui.epam.com/docExample?theme=electric&examplePath=scrollBars%2FWithShadows
2. Open Chrome Dev tools and:

// Change content from scrollable area, so that it does not scroll
document.querySelector('[data-overlayscrollbars-contents]').innerHTML = '<div id="demo-bug" />';

// Add some shadow DOM content big enough to cause vertical scroll
const container = document.getElementById('demo-bug');
container.attachShadow({ mode: "open" });
container.shadowRoot.innerHTML = '<div style="background: linear-gradient(to bottom, aquamarine, #fff); height:5000px" />';

Actual result

No vertical scroll

Expected result

Vertical scroll appears

Environment

• UUI version: 6.3.3
• Browser name: Chrome
• Operating System: Windows 11 Enterprise

[siarheiyelin]

Root cause:

• The overlayscrollbars library uses MutationObserver to detect changes in the scrollable area and update scrollbar elements.
• However, MutationObserver cannot detect changes within a shadow DOM

Workaround:

• Attach a ResizeObserver to the shadow DOM host element and trigger some custom event when this element is resized
• Use the elementEvents property to subscribe overlayscrollbars to this custom event.

E.g.:

/** Custom event name fired when observed elements resize. Used by OverlayScrollbars `update.elementEvents`. */
export const resizeObserverPluginEventName = '__osResizeObserverPlugin:resize';
/**
 * Observes elements matching `selector` inside the scroll container with ResizeObserver.
 * On resize, dispatches a custom event so OverlayScrollbars can refresh.
 * It improves the library's built-in observers, which do not detect size changes of Shadow DOM hosts.
 *
 * @returns Cleanup function that disconnects all observers.
 *
 * @see https://github.com/epam/UUI/issues/2956
 */
export function resizeObserverPlugin(options: {
    /** CSS selector for elements to observe. Prefer a specific selector for performance. */
    selector: string;
    /** OverlayScrollbars instance container. */
    container: HTMLElement;
}): () => void {
    const { selector, container } = options;
    if (!container) {
        return () => {};
    }
    let mutationObserver: MutationObserver;
    const observed = new Map<HTMLElement, ResizeObserver>();

    const observeElement = (element: HTMLElement) => {
        if (observed.has(element)) {
            return;
        }
        const resizeObserver = new ResizeObserver(() => {
            if (!element.isConnected) {
                unobserveElement(element);
                return;
            }
            element.dispatchEvent(
                new CustomEvent(resizeObserverPluginEventName, {
                    bubbles: true,
                }),
            );
        });
        resizeObserver.observe(element);
        observed.set(element, resizeObserver);
    };

    const unobserveElement = (element: HTMLElement) => {
        const observer = observed.get(element);
        if (observer) {
            observer.disconnect();
            observed.delete(element);
        }
    };

    const findAndObserveElements = (root: HTMLElement) => {
        const elements = root.querySelectorAll<HTMLElement>(selector);
        const currentElements = new Set<HTMLElement>();

        elements.forEach((element) => {
            currentElements.add(element);
            observeElement(element);
        });

        Array.from(observed.keys()).forEach((element) => {
            if (!currentElements.has(element)) {
                unobserveElement(element);
            }
        });
    };

    const updateResizeObservers = () => {
        findAndObserveElements(container);
    };

    const destroy = () => {
        mutationObserver.disconnect();
        for (const element of observed.keys()) {
            unobserveElement(element);
        }
    };

    const init = () => {
        updateResizeObservers();
        mutationObserver = new MutationObserver(() => {
            if (!container.isConnected) {
                destroy();
            } else {
                updateResizeObservers();
            }
        });
        mutationObserver.observe(container, {
            attributes: false,
            childList: true,
            subtree: true,
        });
    };

    init();
    return () => {
        destroy();
    };
}

[JuliaMV]

Released in 6.4.3 - 04.02.2026