Scroll Area

A native scroll container with custom scrollbars.

Fugiat adipisicing dolor ut irure. Ut aute Lorem labore est aute quis officia quis consectetur in amet id velit dolore. Occaecat labore adipisicing nostrud veniam. Eu non tempor ipsum. Sunt irure enim enim sint magna laboris ex tempor excepteur nulla est amet culpa.

Est nulla commodo laboris velit ipsum dolore. Magna id anim Lorem labore minim aute irure laboris. Velit elit duis exercitation duis mollit enim cupidatat consectetur mollit non officia deserunt fugiat do deserunt.

<ui:scrollArea.root class="h-50 max-w-90">
    <ui:scrollArea.viewport class="border rounded-md">
        <ui:scrollArea.content>
            <div class="py-3 pr-6 pl-4 text-sm leading-relaxed">
                <p>
                    Fugiat adipisicing dolor ut irure. Ut aute Lorem labore est aute quis officia quis consectetur in amet id velit dolore. Occaecat labore adipisicing nostrud veniam. Eu non tempor ipsum. Sunt irure enim enim sint magna laboris ex tempor excepteur nulla est amet culpa.
                </p>
                <p class="mt-4">
                    Est nulla commodo laboris velit ipsum dolore. Magna id anim Lorem labore minim aute irure laboris. Velit elit duis exercitation duis mollit enim cupidatat consectetur mollit non officia deserunt fugiat do deserunt.
                </p>
            </div>
        </ui:scrollArea.content>
    </ui:scrollArea.viewport>
    <ui:scrollArea.scrollbar>
        <ui:scrollArea.thumb />
    </ui:scrollArea.scrollbar>
</ui:scrollArea.root>

import { mount } from 'fluid-primitives';
import { ScrollArea } from 'fluid-primitives/scroll-area';

mount('scroll-area', ({ props }) => {
	const scrollArea = new ScrollArea(props);
	scrollArea.init();
	return scrollArea;
});

Features

Uses native browser scrolling for performance
Supports vertical and horizontal scrolling
Customizable scrollbar appearance
Supports visibility modes: always, scroll, or hover
Scrollbar thumb reflects the actual scroll position

Installation

typo3 ui:add scroll-area

Read more about installing Components and Primitives.

Examples

Horizontal Scroll

Enable horizontal scrolling for wide content.

Item 1

Item 2

Item 3

Item 4

<ui:scrollArea.root class="w-96">
    <ui:scrollArea.viewport class="border rounded-md">
        <ui:scrollArea.content class="flex gap-4 w-max p-4">
            <div class="w-48 h-32 bg-muted rounded grid place-items-center">Item 1</div>
            <div class="w-48 h-32 bg-muted rounded grid place-items-center">Item 2</div>
            <div class="w-48 h-32 bg-muted rounded grid place-items-center">Item 3</div>
            <div class="w-48 h-32 bg-muted rounded grid place-items-center">Item 4</div>
        </ui:scrollArea.content>
    </ui:scrollArea.viewport>
    <ui:scrollArea.scrollbar orientation="{f:constant(name: 'Jramke\FluidPrimitives\Enum\Orientation::Horizontal')}">
        <ui:scrollArea.thumb />
    </ui:scrollArea.scrollbar>
</ui:scrollArea.root>

Both Directions

Support scrolling in both vertical and horizontal directions.

Large content that scrolls in both directions.

<ui:scrollArea.root class="h-72 w-72">
    <ui:scrollArea.viewport class="border rounded-md">
        <ui:scrollArea.content class="w-[500px] h-[500px] p-4">
            <p class="text-sm">Large content that scrolls in both directions.</p>
            <div class="mt-4 grid grid-cols-3 gap-4">
                <div class="w-32 h-32 bg-muted rounded"></div>
                <div class="w-32 h-32 bg-muted rounded"></div>
                <div class="w-32 h-32 bg-muted rounded"></div>
                <div class="w-32 h-32 bg-muted rounded"></div>
                <div class="w-32 h-32 bg-muted rounded"></div>
                <div class="w-32 h-32 bg-muted rounded"></div>
                <div class="w-32 h-32 bg-muted rounded"></div>
                <div class="w-32 h-32 bg-muted rounded"></div>
                <div class="w-32 h-32 bg-muted rounded"></div>
            </div>
        </ui:scrollArea.content>
    </ui:scrollArea.viewport>
    <ui:scrollArea.scrollbar orientation="{f:constant(name: 'Jramke\FluidPrimitives\Enum\Orientation::Vertical')}">
        <ui:scrollArea.thumb />
    </ui:scrollArea.scrollbar>
    <ui:scrollArea.scrollbar orientation="{f:constant(name: 'Jramke\FluidPrimitives\Enum\Orientation::Horizontal')}">
        <ui:scrollArea.thumb />
    </ui:scrollArea.scrollbar>
</ui:scrollArea.root>

API Reference

The following tables cover the available props of the Fluid Primitives. For a full list of available client side props and methods, see the Zag.js Machine API.

scrollArea.root

Provides the scroll area container and shared state. Renders a <div> element.

scrollArea.viewport

Provides the native scrollable viewport. Renders a <div> element.

scrollArea.content

Wraps the scrollable content to measure its size. Renders a <div> element.

scrollArea.scrollbar

Displays a custom scrollbar track. Renders a <div> element.

Name	Description	Required	Default
`orientation`	`Enum\Orientation` The orientation of the scrollbar.	No	Vertical

scrollArea.thumb

Displays the draggable scrollbar thumb. Renders a <div> element.

Anatomy

<primitives:scrollArea.root>
    <primitives:scrollArea.viewport>
        <primitives:scrollArea.content />
    </primitives:scrollArea.viewport>
    <primitives:scrollArea.scrollbar>
        <primitives:scrollArea.thumb />
    </primitives:scrollArea.scrollbar>
</primitives:scrollArea.root>