Custom Scrollbar

Place ThemeScrollbar in the root layout

Mount ThemeScrollbar once in your root layout — not inside individual pages or components. The engine discovers every scrollable container on the page (including ones added later by client-side navigation), so a single mount covers the entire app.

Import the scrollbar CSS in your global stylesheet

Add the import to your global CSS file so the pre-paint native-bar hiding and overlay strip base styles are available before the first paint. This prevents a flash of native scrollbars on initial load.

Recommended configuration

How it integrates with your theme

The thumb is the only surface that takes a theme color, and you never set it. On mount the engine tries primary, then accent, then foreground, keeps the first that contrasts with background, and writes it to --tv-scrollbar-thumb; hover and active are derived from it. The track is transparent and the arrows inherit currentColor, so switching themes only ever moves the thumb — no re-mount, and nothing else to configure.

Best practices

• Scope the overlay with include / exclude — CSS selectors for inner scrollables; the document is always tracked. The framework components group the same pair under scope, so there it is scope={{ include: [".panel"] }} rather than a top-level prop.
• Pass custom arrow icons via the icons group for framework-owned rendering (JSX, VNodes, etc.).

Lifecycle and reactivity

The overlay owns the native bar for exactly as long as it is mounted, and every option is live.

• Every prop is reactive. Changing one — on the component, or by setting the matching attribute on themvora-scrollbar directly — rebuilds the overlay in place. The replacement is created before the incumbent is destroyed, so the page never passes through a frame with the native bar back and nothing drawing.
• Unmounting restores the native scrollbar. The overlay, its observers and its DOM nodes go away with the component, and so does the native-bar hiding — the platform scrollbar returns. Removing the element is therefore a supported way to turn the feature off, not a way to break the page.
• The SSR pre-paint hiding is provisional. A server-rendered tv-scrollbar class only hides the native bar; the overlay is what replaces it. If a page enables pre-paint hiding but renders no overlay element — the component was omitted, or commented out — the class and the hiding stylesheet are removed at the end of <body> and the native scrollbar comes back. A mismatch degrades to a native scrollbar, never to no scrollbar at all.

All color options accept any valid CSS color string (hex, rgb, hsl, named colors, CSS variables, etc.).

• thumbColor — base thumb color. Default: theme-derived.
• trackColor — track background color. Default: transparent (theme-derived wash).
• thumbHoverColor — thumb color on hover. Default: same as thumbColor.
• activeThumbColor — thumb color while dragging. Default: same as thumbColor.

You can also theme via CSS custom properties — this is useful for dark/light mode pairs or global design tokens:

:root {
  --tv-scrollbar-thumb: #ff6b6b;
  --tv-scrollbar-track: #2d2d2d;
  --tv-scrollbar-thumb-hover: #ff8888;
  --tv-scrollbar-thumb-active: #ff4444;
}

/* Dark mode override */
.dark {
  --tv-scrollbar-thumb: #7c3aed;
  --tv-scrollbar-track: #1e1e1e;
  --tv-scrollbar-thumb-hover: #a855f7;
  --tv-scrollbar-thumb-active: #d946ef;
}

The CSS variables are defined on the overlay host element ([data-themvora-host]) with theme-derived defaults, so the scrollbar automatically follows your active theme. Custom values override the defaults.

Programmatic mount

Create a theme store and pass it to createThemeScrollbar (alias for createOverlayScrollbar). Returns an OverlayScrollbarHandle or null on SSR/coarse-pointer devices.

import {
  createThemeRuntime,
  createThemeScrollbar,
} from "@themvora/core";
import "@themvora/core/scrollbar.css";

const runtime = createThemeRuntime({
  defaultTheme: "light",
});

// One call mounts the overlay and discovers every scrollable container
// on the page. Returns an OverlayScrollbarHandle (or null on SSR /
// coarse-pointer devices).
const handle = createThemeScrollbar(runtime.store, {
  autoHide: true,
  arrows: true,
  thickness: 8,
  radius: 999,
});

// The strips recolor automatically when the theme changes.
runtime.selection.setMode("dark");

Hide the native bar before first paint

Framework providers bootstrap this for you. In vanilla settings, drop a blocking pre-paint script into <head> so the native scrollbar is never painted (it runs in under 1 ms and skips coarse-pointer devices unless you pass { touch: true }).

import { createPrePaintScrollbarScript } from "@themvora/core";

// Called once in your server render or build step. The generated
// <script> is blocking, runs in <1ms, and is idempotent.
const head = [
  "<!doctype html>",
  "<html>",
  "  <head>",
  `    <script>${createPrePaintScrollbarScript()}</script>`,
  '    <link rel="stylesheet" href="/scrollbar.css" />',
  "  </head>",
  "</html>",
  ].join("\n");

If you're already server-rendering markup, you can skip the script and inline createPrePaintScrollbarCSS() as a <style> alongside a tv-scrollbar class on <html> — no blocking script, no hydration mismatch.

import { createPrePaintScrollbarCSS } from "@themvora/core";

// In your server-rendered <head>: hidden from the very first paint,
// no blocking <script>, and no hydration mismatches.
export function Head() {
  return (
    <head>
      <html lang="en" className="tv-scrollbar" />
      <style dangerouslySetInnerHTML={{ __html: createPrePaintScrollbarCSS() }} />
    </head>
  );
}