Scroll Area

# Brok UI: Scroll Area (`scroll-area`)

A scrollable region with a custom, themeable scrollbar.

Brok UI is a Laravel Blade component registry. Installed components are plain Blade files the app owns.

## Install

```bash
php artisan ui:add scroll-area
```

## Usage

```blade
<x-ui.scroll-area class="h-48 w-64 rounded-md border border-border">
    <x-ui.scroll-area.viewport class="p-4">
        <h4 class="mb-4 text-sm font-medium leading-none">{{ __('Tags') }}</h4>
        <div class="text-sm">{{ __('tags v1.0.0') }}</div>
        <div class="mt-3 text-sm">{{ __('tags v1.1.0') }}</div>
        <div class="mt-3 text-sm">{{ __('tags v1.2.0') }}</div>
        <div class="mt-3 text-sm">{{ __('tags v1.3.0') }}</div>
        <div class="mt-3 text-sm">{{ __('tags v1.4.0') }}</div>
        <div class="mt-3 text-sm">{{ __('tags v1.5.0') }}</div>
        <div class="mt-3 text-sm">{{ __('tags v1.6.0') }}</div>
        <div class="mt-3 text-sm">{{ __('tags v1.7.0') }}</div>
        <div class="mt-3 text-sm">{{ __('tags v1.8.0') }}</div>
        <div class="mt-3 text-sm">{{ __('tags v1.9.0') }}</div>
        <div class="mt-3 text-sm">{{ __('tags v2.0.0') }}</div>
        <div class="mt-3 text-sm">{{ __('tags v2.1.0') }}</div>
        <div class="mt-3 text-sm">{{ __('tags v2.2.0') }}</div>
        <div class="mt-3 text-sm">{{ __('tags v2.3.0') }}</div>
        <div class="mt-3 text-sm">{{ __('tags v2.4.0') }}</div>
    </x-ui.scroll-area.viewport>
    <x-ui.scroll-area.scrollbar>
        <x-ui.scroll-area.thumb />
    </x-ui.scroll-area.scrollbar>
</x-ui.scroll-area>
```

## Use when

- Use to structure hierarchy, spacing, and responsiveness so content is easier to scan and navigate.
- Bounding a block of content (a list, a code sample, a long menu) to a fixed height with a themeable, overlay-style scrollbar.
- Wanting native scroll and keyboard behavior while hiding the browser's default scrollbar chrome.

## Avoid when

- Do not let layout primitives substitute for semantics, headings, or interaction rules users still need.
- The content should scroll horizontally within a padded parent; use bleed with scroll instead.
- The page itself should scroll normally; scroll-area is for a bounded region, not the whole viewport.

## Anti-patterns

- Using visual layout as a substitute for semantic structure

## Rules

- Use the `<brok:scroll-area>` tag (or `<x-ui.scroll-area>`) in Blade; do not rewrite the component.
- Prefer the documented props and variants over utility-class overrides; when a utility must win, use the `!` important modifier.
- Use semantic design tokens (`bg-primary`, `text-muted-foreground`), never raw colour utilities.
- Keep the `data-slot` attributes; they are the styling and test hooks.

## Links

- Docs: https://brokui.dev/docs/components/scroll-area
- Registry JSON (files, props, contract): https://brokui.dev/r/open/scroll-area.json

/**
 * Scroll Area behavior.
 *
 * Renders an overlay scrollbar thumb that mirrors the native scroll position of a
 * viewport. Native scrolling and keyboard interaction stay fully functional —
 * the native scrollbar is only hidden visually. The bar is `active` (shown)
 * while the pointer is over the area, for a moment after each scroll, and while
 * the thumb is being dragged; a click on the track pages toward the click.
 *
 * `thumbHeight` is the visible-to-total ratio (as a percentage of the track) and
 * `thumbTop` is how far the thumb has travelled down the remaining track space.
 *
 * Self-registers on `alpine:init` so import order does not matter — import this
 * file once from your bundle (e.g. resources/js/ui/index.js).
 */
document.addEventListener('alpine:init', () => {
    window.Alpine.data('uiScrollArea', () => ({
        thumbHeight: 100,
        thumbTop: 0,
        active: false,
        dragging: false,
        _idle: null,
        _move: null,
        _up: null,

        onScroll() {
            const v = this.$refs.viewport;
            if (!v) {
                return;
            }

            const ratio = v.scrollHeight > 0 ? v.clientHeight / v.scrollHeight : 1;
            this.thumbHeight = Math.min(100, ratio * 100);

            const maxScroll = v.scrollHeight - v.clientHeight;
            this.thumbTop = maxScroll > 0
                ? (v.scrollTop / maxScroll) * (100 - this.thumbHeight)
                : 0;

            if (!isFinite(this.thumbTop)) {
                this.thumbTop = 0;
            }

            // Show the bar while scrolling, then let it fade once the content settles.
            this.active = true;
            clearTimeout(this._idle);
            this._idle = setTimeout(() => {
                if (!this.dragging && !this.$root.matches(':hover')) this.active = false;
            }, 800);
        },

        /** Drag the thumb: pointer travel maps onto scroll travel in the same ratio. */
        startDrag(event) {
            const v = this.$refs.viewport;
            const track = this.$refs.scrollbar;
            if (!v || !track) return;
            event.preventDefault();
            this.dragging = true;
            this.active = true;
            const startY = event.clientY;
            const startTop = v.scrollTop;
            const trackHeight = track.clientHeight;
            this._move = (e) => {
                const travel = (e.clientY - startY) / trackHeight;
                v.scrollTop = startTop + travel * v.scrollHeight;
            };
            this._up = () => {
                this.dragging = false;
                document.removeEventListener('pointermove', this._move);
                document.removeEventListener('pointerup', this._up);
                document.removeEventListener('pointercancel', this._up);
                if (!this.$root.matches(':hover')) this.active = false;
            };
            document.addEventListener('pointermove', this._move);
            document.addEventListener('pointerup', this._up);
            document.addEventListener('pointercancel', this._up);
        },

        /** A click on the track pages the viewport toward the click. */
        pageTo(event) {
            const v = this.$refs.viewport;
            const track = this.$refs.scrollbar;
            if (!v || !track) return;
            const rect = track.getBoundingClientRect();
            const thumbCentre = rect.top + (rect.height * (this.thumbTop + this.thumbHeight / 2)) / 100;
            v.scrollBy({ top: event.clientY < thumbCentre ? -v.clientHeight : v.clientHeight, behavior: 'smooth' });
        },

        destroy() {
            clearTimeout(this._idle);
            if (this._move) document.removeEventListener('pointermove', this._move);
            if (this._up) {
                document.removeEventListener('pointerup', this._up);
                document.removeEventListener('pointercancel', this._up);
            }
        },
    }));
});