Scroll Area

A customizable container that adds scrollbars when content overflows its boundaries.

Lorem ipsum dolor sit, amet consectetur adipisicing elit. Dignissimos impedit rem, repellat deserunt ducimus quasi nisi voluptatem cumque aliquid esse ea deleniti eveniet incidunt! Deserunt minus laborum accusamus iusto dolorum. Lorem ipsum dolor sit, amet consectetur adipisicing elit. Blanditiisofficiiserrorminimaeos fugit voluptate excepturi eveniet dolore et, ratione impedit consequuntur dolorem hic quae corrupti autem? Dolorem, sit voluptatum.

import { component$, useStyles$ } from "@builder.io/qwik";
import { ScrollArea } from "@kunai-consulting/qwik";
import styles from "./scroll-area.css?inline";

export default component$(() => {
  useStyles$(styles);
  return (
    <ScrollArea.Root class="!h-[200px] !w-[250px] rounded-md border p-4 scroll-area-root">
      <ScrollArea.Viewport class="scroll-area-viewport">
        <div class="p-4">
          <p>
            Lorem ipsum dolor sit, amet consectetur adipisicing elit. Dignissimos impedit
            rem, repellat deserunt ducimus quasi nisi voluptatem cumque aliquid esse ea
            deleniti eveniet incidunt! Deserunt minus laborum accusamus iusto dolorum.
            Lorem ipsum dolor sit, amet consectetur adipisicing elit.
            Blanditiisofficiiserrorminimaeos fugit voluptate excepturi eveniet dolore et,
            ratione impedit consequuntur dolorem hic quae corrupti autem? Dolorem, sit
            voluptatum.
          </p>
        </div>
      </ScrollArea.Viewport>

      <ScrollArea.Scrollbar orientation="vertical" class="scroll-area-scrollbar">
        <ScrollArea.Thumb class="scroll-area-thumb" />
      </ScrollArea.Scrollbar>

      <ScrollArea.Scrollbar orientation="horizontal" class="scroll-area-scrollbar">
        <ScrollArea.Thumb class="scroll-area-thumb" />
      </ScrollArea.Scrollbar>
    </ScrollArea.Root>
  );
});

Features

Custom scrollbar visibility modes (hover, scroll, auto, always)
Draggable thumb with smooth scroll tracking
Two-axis scrolling support (vertical and horizontal)
Overflow detection and automatic scrollbar display
Click-to-scroll on track functionality
Zoom level detection and overflow adjustment
WAI-ARIA compliant scrollable region
Scroll position memory during thumb dragging
Configurable scrollbar hide delay
Responsive to window resize events
Cross-browser zoom handling
Dynamic thumb size based on content

Anatomy

Part	Description
<ScrollArea.Root>	A root component for scrollable content areas with customizable scrollbar behavior
<ScrollArea.Viewport>	—
<ScrollArea.Scrollbar>	A scrollbar component that can be oriented vertically or horizontally
<ScrollArea.Thumb>	A draggable thumb component for the scrollbar that handles scroll position

Examples

Basic Usage

The scroll area component provides a customizable scrolling experience with different visibility modes for the scrollbars. The type prop controls when scrollbars are visible:

"hover" (default): Shows scrollbars on hover
"scroll": Shows scrollbars during scrolling
"auto": Shows scrollbars when content overflows
"always": Shows scrollbars whenever there's overflow

Lorem ipsum dolor sit, amet consectetur adipisicing elit. Dignissimos impedit rem, repellat deserunt ducimus quasi nisi voluptatem cumque aliquid esse ea deleniti eveniet incidunt! Deserunt minus laborum accusamus iusto dolorum. Lorem ipsum dolor sit, amet consectetur adipisicing elit. Blanditiis officiis error minima eos fugit voluptate excepturi eveniet dolore et, ratione impedit consequuntur dolorem hic quae corrupti autem? Dolorem, sit voluptatum.

import { component$, useStyles$ } from "@builder.io/qwik";
import { ScrollArea } from "@kunai-consulting/qwik";
import styles from "./scroll-area.css?inline";

export default component$(() => {
  useStyles$(styles);
  return (
    <ScrollArea.Root class="!h-[200px] !w-[350px] rounded-md border p-4 scroll-area-root">
      <ScrollArea.Viewport class="scroll-area-viewport">
        <div class="p-4">
          <p>
            Lorem ipsum dolor sit, amet consectetur adipisicing elit. Dignissimos impedit
            rem, repellat deserunt ducimus quasi nisi voluptatem cumque aliquid esse ea
            deleniti eveniet incidunt! Deserunt minus laborum accusamus iusto dolorum.
            Lorem ipsum dolor sit, amet consectetur adipisicing elit. Blanditiis officiis
            error minima eos fugit voluptate excepturi eveniet dolore et, ratione impedit
            consequuntur dolorem hic quae corrupti autem? Dolorem, sit voluptatum.
          </p>
        </div>
      </ScrollArea.Viewport>

      <ScrollArea.Scrollbar orientation="vertical" class="scroll-area-scrollbar">
        <ScrollArea.Thumb class="scroll-area-thumb" />
      </ScrollArea.Scrollbar>
    </ScrollArea.Root>
  );
});

Visual Features

Horizontal Scrolling

For content that extends beyond the horizontal bounds, use the orientation="horizontal" prop on ScrollArea.Scrollbar.

Lorem ipsum dolor sit, amet consectetur adipisicing elit. Dignissimos impedit rem, repellat deserunt ducimus quasi nisi voluptatem cumque aliquid esse ea deleniti eveniet incidunt! Deserunt minus laborum accusamus iusto dolorum. Lorem ipsum dolor sit, amet consectetur adipisicing elit. Blanditiis officiis error minima eos fugit voluptate excepturi eveniet dolore et, ratione impedit consequuntur dolorem hic quae corrupti autem? Dolorem, sit voluptatum.

import { component$, useStyles$ } from "@builder.io/qwik";
import { ScrollArea } from "@kunai-consulting/qwik";
import styles from "./scroll-area.css?inline";

export default component$(() => {
  useStyles$(styles);
  return (
    <ScrollArea.Root class="!h-[200px] !w-[100px] rounded-md border p-4 scroll-area-root">
      <ScrollArea.Viewport class="scroll-area-viewport">
        <div class="p-4">
          <p>
            Lorem ipsum dolor sit, amet consectetur adipisicing elit. Dignissimos impedit
            rem, repellat deserunt ducimus quasi nisi voluptatem cumque aliquid esse ea
            deleniti eveniet incidunt! Deserunt minus laborum accusamus iusto dolorum.
            Lorem ipsum dolor sit, amet consectetur adipisicing elit. Blanditiis officiis
            error minima eos fugit voluptate excepturi eveniet dolore et, ratione impedit
            consequuntur dolorem hic quae corrupti autem? Dolorem, sit voluptatum.
          </p>
        </div>
      </ScrollArea.Viewport>

      <ScrollArea.Scrollbar orientation="horizontal" class="scroll-area-scrollbar">
        <ScrollArea.Thumb class="scroll-area-thumb" />
      </ScrollArea.Scrollbar>
    </ScrollArea.Root>
  );
});

Both Axes Scrolling

When content overflows in both directions, you can include both vertical and horizontal scrollbars.

import { component$, useStyles$ } from "@builder.io/qwik";
import { ScrollArea } from "@kunai-consulting/qwik";
import styles from "./scroll-area.css?inline";

export default component$(() => {
  useStyles$(styles);
  return (
    <ScrollArea.Root class="!h-[200px] !w-[250px] rounded-md border p-4 scroll-area-root">
      <ScrollArea.Viewport class="scroll-area-viewport">
        <div class="p-4">
          <p>
            Lorem ipsum dolor sit, amet consectetur adipisicing elit. Dignissimos impedit
            rem, repellat deserunt ducimus quasi nisi voluptatem cumque aliquid esse ea
            deleniti eveniet incidunt! Deserunt minus laborum accusamus iusto dolorum.
            Lorem ipsum dolor sit, amet consectetur adipisicing elit.
            Blanditiisofficiiserrorminimaeos fugit voluptate excepturi eveniet dolore et,
            ratione impedit consequuntur dolorem hic quae corrupti autem? Dolorem, sit
            voluptatum.
          </p>
        </div>
      </ScrollArea.Viewport>

      <ScrollArea.Scrollbar orientation="vertical" class="scroll-area-scrollbar">
        <ScrollArea.Thumb class="scroll-area-thumb" />
      </ScrollArea.Scrollbar>

      <ScrollArea.Scrollbar orientation="horizontal" class="scroll-area-scrollbar">
        <ScrollArea.Thumb class="scroll-area-thumb" />
      </ScrollArea.Scrollbar>
    </ScrollArea.Root>
  );
});

Advanced Usage

Custom Hide Delay

For scroll-triggered visibility (type="scroll"), customize how long scrollbars remain visible after scrolling stops using the hideDelay prop (in milliseconds).

import { component$, useStyles$ } from "@builder.io/qwik";
import { ScrollArea } from "@kunai-consulting/qwik";
import styles from "./scroll-area.css?inline";

export default component$(() => {
  useStyles$(styles);
  return (
    <ScrollArea.Root class="!h-[200px] !w-[250px] rounded-md border p-4 scroll-area-root">
      <ScrollArea.Viewport class="scroll-area-viewport">
        <div class="p-4">
          <p>
            Lorem ipsum dolor sit, amet consectetur adipisicing elit. Dignissimos impedit
            rem, repellat deserunt ducimus quasi nisi voluptatem cumque aliquid esse ea
            deleniti eveniet incidunt! Deserunt minus laborum accusamus iusto dolorum.
            Lorem ipsum dolor sit, amet consectetur adipisicing elit.
            Blanditiisofficiiserrorminimaeos fugit voluptate excepturi eveniet dolore et,
            ratione impedit consequuntur dolorem hic quae corrupti autem? Dolorem, sit
            voluptatum.
          </p>
        </div>
      </ScrollArea.Viewport>

      <ScrollArea.Scrollbar orientation="vertical" class="scroll-area-scrollbar">
        <ScrollArea.Thumb class="scroll-area-thumb" />
      </ScrollArea.Scrollbar>

      <ScrollArea.Scrollbar orientation="horizontal" class="scroll-area-scrollbar">
        <ScrollArea.Thumb class="scroll-area-thumb" />
      </ScrollArea.Scrollbar>
    </ScrollArea.Root>
  );
});

Note: The examples demonstrate the core functionality of the scroll area component. The hideDelay prop (default: 600ms) determines how long scrollbars remain visible after scrolling stops when using type="scroll".

Component State

The ScrollArea component offers several ways to control its scrollbar visibility and behavior through state management.

Using Component State

Scrollbar Visibility Types

The ScrollArea provides four visibility modes controlled through the type prop on ScrollArea.Root:

Auto Mode Shows scrollbars when content overflows and hides them when it doesn't.

import { component$, useStyles$ } from "@builder.io/qwik";
import { ScrollArea } from "@kunai-consulting/qwik";
import styles from "./scroll-area.css?inline";

export default component$(() => {
  useStyles$(styles);
  return (
    <ScrollArea.Root class="!h-[200px] !w-[250px] rounded-md border p-4 scroll-area-root">
      <ScrollArea.Viewport class="scroll-area-viewport">
        <div class="p-4">
          <p>
            Lorem ipsum dolor sit, amet consectetur adipisicing elit. Dignissimos impedit
            rem, repellat deserunt ducimus quasi nisi voluptatem cumque aliquid esse ea
            deleniti eveniet incidunt! Deserunt minus laborum accusamus iusto dolorum.
            Lorem ipsum dolor sit, amet consectetur adipisicing elit.
            Blanditiisofficiiserrorminimaeos fugit voluptate excepturi eveniet dolore et,
            ratione impedit consequuntur dolorem hic quae corrupti autem? Dolorem, sit
            voluptatum.
          </p>
        </div>
      </ScrollArea.Viewport>

      <ScrollArea.Scrollbar orientation="vertical" class="scroll-area-scrollbar">
        <ScrollArea.Thumb class="scroll-area-thumb" />
      </ScrollArea.Scrollbar>

      <ScrollArea.Scrollbar orientation="horizontal" class="scroll-area-scrollbar">
        <ScrollArea.Thumb class="scroll-area-thumb" />
      </ScrollArea.Scrollbar>
    </ScrollArea.Root>
  );
});

Always Mode Keeps scrollbars visible whenever content overflows, regardless of user interaction.
Hover Mode Shows scrollbars only when the user hovers over the scroll area.
Scroll Mode Displays scrollbars only during active scrolling.

Hide Delay Configuration

When using the "scroll" visibility type, you can customize how long the scrollbars remain visible after scrolling stops using the hideDelay prop:

<ScrollArea.Root type="scroll" hideDelay={1000}>
  {/* Content */}
</ScrollArea.Root>

State Interactions

Overflow Detection

The ScrollArea automatically detects content overflow and updates its state accordingly. This state is reflected through the data-has-overflow attribute on the root element.

Scrollbar State

Scrollbars expose their current visibility state through the data-state attribute, which can be either "visible" or "hidden". This state updates automatically based on:

The chosen visibility type
Content overflow status
User interactions (hover, scroll)
Window resize events
Zoom level changes

Thumb Position

The thumb position automatically updates to reflect the current scroll position. You can programmatically control the scroll position through the viewport:

const viewport = document.querySelector('[data-qds-scroll-area-viewport]');
if (viewport) {
  viewport.scrollTop = 100; // Scroll vertically
  viewport.scrollLeft = 50; // Scroll horizontally
}

Drag State

During thumb dragging, the thumb element receives a data-dragging attribute that can be used for styling:

[data-qds-scroll-area-thumb][data-dragging] {
  /* Styles for dragging state */
}

The ScrollArea maintains the scroll position relative to the drag position, ensuring smooth scrolling even when the cursor moves outside the scrollbar bounds.

Based on the provided implementation and examples, I'll document the ScrollArea configuration options:

Scrollbar Visibility

Core Behavior

The ScrollArea component supports four visibility modes controlled by the type prop on ScrollArea.Root:

hover (default): Shows scrollbars when hovering over the scroll area
scroll: Displays scrollbars during scrolling, then hides after delay
auto: Always shows scrollbars when content overflows
always: Permanently displays scrollbars when content overflows As shown in the hover-test example above, the hover mode provides a clean interface that reveals scrollbars only when needed.

Hide Delay

For the scroll type, you can customize how long scrollbars remain visible after scrolling stops using the hideDelay prop:

type ScrollAreaRootProps = {
  hideDelay?: number; // milliseconds, defaults to 600
}

As shown in the custom-delay-test example above, this allows fine-tuning of the scrollbar fade-out timing.

Scrollbar Configuration

Orientation Support

ScrollArea supports both vertical and horizontal scrollbars through the orientation prop on ScrollArea.Scrollbar:

type ScrollbarOrientation = "vertical" | "horizontal";

As shown in the both example above, you can include both orientations simultaneously for content that overflows in both directions.

Technical Constraints

Scrollbar visibility is automatically managed based on content overflow
Thumb size and position are dynamically calculated based on viewport and content dimensions
Scrollbars maintain position during window resize and zoom operations
Custom scroll behavior is preserved across browser zoom levels (25% to 500%)

Performance Considerations

The ScrollArea implements several optimizations:

Throttled resize handling to prevent excessive recalculation
Efficient thumb position updates using transform
Minimal DOM updates during scroll operations
Lazy initialization of overflow detection These ensure smooth scrolling performance even with large content areas and frequent updates.

API Reference

Scroll Area Thumb

Inherits from: <div />

Props

Prop	Type	Default
ref	Signal<HTMLDivElement \| undefined>	-
onDragStart$	PropFunction<(e: MouseEvent) => void>	-
onDragMove$	PropFunction<(e: MouseEvent) => void>	-
onDragEnd$	PropFunction<() => void>	-

Data Attributes

Attribute	Description
data-dragging	Indicates whether the thumb is currently being dragged

Scroll Area Scrollbar

Inherits from: <div />

Props

Prop	Type	Default	Description
orientation	"vertical" \| "horizontal"	"vertical"
onScroll$	QRL<(e: Event) => void>	-

Data Attributes

Attribute	Description
data-orientation
data-state	Indicates the visibility state of the scrollbar (visible or hidden)

Scroll Area Root

Inherits from: <div />

Data Attributes

Attribute	Description
data-type	Defines the scrollbar visibility behavior (hover, scroll, auto, or always)
data-has-overflow	Indicates whether the content exceeds the viewport dimensions

Scroll Area View Port

Inherits from: <div />

Props

Prop	Type	Default	Description
onScroll$	PropFunction<(e: Event) => void>	-

Accessibility

Keyboard Interactions

Key	Description
ArrowDown	Scrolls the viewport content vertically downward when focus is on the viewport
ArrowUp	Scrolls the viewport content vertically upward when focus is on the viewport
ArrowRight	Scrolls the viewport content horizontally to the right when focus is on the viewport
ArrowLeft	Scrolls the viewport content horizontally to the left when focus is on the viewport
PageDown	Scrolls the viewport content down by a larger increment when focus is on the viewport
PageUp	Scrolls the viewport content up by a larger increment when focus is on the viewport
Home	Scrolls to the top of the viewport content when focus is on the viewport
End	Scrolls to the bottom of the viewport content when focus is on the viewport
Ctrl/Cmd + 0	Triggers overflow check when zooming to default level
Ctrl/Cmd + +/=	Triggers overflow check when zooming in
Ctrl/Cmd + -	Triggers overflow check when zooming out