MacOS WKWebView Custom Scrollbars

The Problem

WKWebView on macOS does not support standard CSS scrollbar styling:

• •::-webkit-scrollbar pseudo-elements are ignored
• •scrollbar-color and scrollbar-width CSS properties don't work reliably
• •Native scrollbars always render with system appearance

This means CSS-based scrollbar theming that works in browsers will NOT work in the native macOS app.

The Solution: Negative Margin Technique

Hide the native scrollbar using pure CSS layout (not pseudo-elements):

1. •Outer wrapper: overflow: hidden clips the native scrollbar
2. •Inner scrollable div: overflow-y: scroll + marginRight: -20px pushes scrollbar outside
3. •Padding compensation: paddingRight: 20px ensures content isn't cut off
4. •Custom overlay: Render a themed scrollbar as a positioned DOM element

Usage

Use the OverlayScrollbar component from @/components/OverlayScrollbar:

import { OverlayScrollbar } from "@/components/OverlayScrollbar";

// Basic usage
<OverlayScrollbar className="h-full">
    <div>Your scrollable content here</div>
</OverlayScrollbar>

// With scroll position persistence
const scrollRef = useTabScrollPersistence(tabId);

<OverlayScrollbar
    scrollRef={scrollRef}
    className="flex-1 h-full"
    style={{ backgroundColor: currentTheme.styles.surfacePrimary }}
>
    <div>Content with scroll position saved</div>
</OverlayScrollbar>

Component Props

Features

• •Theme-aware: Uses currentTheme.styles.borderDefault for scrollbar color
• •Auto-hide: Scrollbar fades out after 1 second of inactivity
• •Hover to show: Scrollbar appears when hovering the container
• •Drag support: Click and drag the thumb to scroll
• •Track click: Click the track to jump to position
• •Resize-aware: Updates when content or container size changes

When to Use

Use OverlayScrollbar instead of native overflow-y-auto when:

• •The scroll container needs themed scrollbars
• •The component renders in the macOS WKWebView app
• •You want consistent scrollbar appearance across web and native

When NOT to Use

• •Very small scroll areas (the overlay adds complexity)
• •Performance-critical lists with thousands of items (consider virtualization)
• •Areas where native scrollbar behavior is preferred

Implementation Details

See the full component at: src/components/OverlayScrollbar.tsx

Key constants:

• •SCROLLBAR_WIDTH = 20 - Margin to hide native scrollbar (macOS scrollbar is ~15-17px)
• •Thumb minimum height: 30px
• •Hide delay: 1000ms after scroll stops
• •Fade transition: 150ms

Scroll Position Persistence for Tabs

When implementing scroll persistence for workspace tabs, use useTabScrollPersistence with OverlayScrollbar.

How It Works

1. •

   useTabScrollPersistence(tabId) returns a ref and:

   • •Saves scroll position to a module-level Map on every scroll event
   • •Restores position when the component mounts (using ResizeObserver/MutationObserver for async content)
2. •

   Pass the ref to OverlayScrollbar:

   tsx

   const scrollRef = useTabScrollPersistence(tabId);
   
   <OverlayScrollbar scrollRef={scrollRef} className="flex-1">
       {/* content */}
   </OverlayScrollbar>
   

Critical Rule: Keep OverlayScrollbar Mounted

The ref must be attached to a mounted element when useTabScrollPersistence's effect runs.

If you conditionally render a different tree during loading, the ref won't be set and restoration will fail:

// BAD - OverlayScrollbar unmounts during loading, ref is null when effect runs
if (isLoading) {
    return <Loader />;  // Different tree, no OverlayScrollbar!
}

return (
    <OverlayScrollbar scrollRef={scrollRef}>
        {/* content */}
    </OverlayScrollbar>
);

// GOOD - OverlayScrollbar stays mounted, ref is always set
return (
    <OverlayScrollbar scrollRef={scrollRef} className="flex-1">
        {isLoading ? (
            <div className="flex h-full items-center justify-center">
                <Loader />
            </div>
        ) : (
            {/* actual content */}
        )}
    </OverlayScrollbar>
);

Why This Matters

The useTabScrollPersistence hook runs its effect on mount with [tabId] dependency:

useEffect(() => {
    const element = scrollRef.current;
    if (!element) return;  // Early return if ref not set!

    // Set up observers and attempt restoration...
}, [tabId]);

If the element isn't mounted when the effect runs:

1. •scrollRef.current is null
2. •Effect returns early without setting up observers
3. •When content loads and OverlayScrollbar mounts, the effect doesn't re-run
4. •No scroll restoration happens

Checklist for Scroll Persistence

• • Use OverlayScrollbar (not native overflow-y-auto) for the scroll container
• • Pass scrollRef from useTabScrollPersistence to OverlayScrollbar
• • Keep OverlayScrollbar in the component tree during ALL render states (loading, error, etc.)
• • Render loading/error states as CHILDREN of OverlayScrollbar, not as alternative returns

Key Files

References

• •CSS Negative Margin Technique
• •WKWebView Scrollbar Limitations - Apache JIRA
• •Apple Developer Forums - WKWebView Scroll