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.

Rendered data attributes

Attribute	Description
`data-scope`	scroll-area
`data-part`	root
`data-overflow-x`	Present when the content overflows the x-axis
`data-overflow-y`	Present when the content overflows the y-axis

scrollArea.viewport

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

Rendered data attributes

Attribute	Description
`data-scope`	scroll-area
`data-part`	viewport
`data-at-top`	Present when scrolled to the top edge
`data-at-bottom`	Present when scrolled to the bottom edge
`data-at-left`	Present when scrolled to the left edge
`data-at-right`	Present when scrolled to the right edge
`data-overflow-x`	Present when the content overflows the x-axis
`data-overflow-y`	Present when the content overflows the y-axis

scrollArea.content

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

Rendered data attributes

Attribute	Description
`data-scope`	scroll-area
`data-part`	content
`data-overflow-x`	Present when the content overflows the x-axis
`data-overflow-y`	Present when the content overflows the y-axis

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

Rendered data attributes

Attribute	Description
`data-scope`	scroll-area
`data-part`	scrollbar
`data-orientation`	The orientation of the scrollbar
`data-scrolling`	Present when scrolling
`data-hover`	Present when hovered
`data-dragging`	Present when in the dragging state
`data-overflow-x`	Present when the content overflows the x-axis
`data-overflow-y`	Present when the content overflows the y-axis

scrollArea.thumb

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

Rendered data attributes

Attribute	Description
`data-scope`	scroll-area
`data-part`	thumb
`data-orientation`	The orientation of the thumb
`data-hover`	Present when hovered
`data-dragging`	Present when in the dragging state

Machine JavaScript API

Name	Type	Description
`isAtTop`	`boolean`	Whether the scroll area is at the top
`isAtBottom`	`boolean`	Whether the scroll area is at the bottom
`isAtLeft`	`boolean`	Whether the scroll area is at the left
`isAtRight`	`boolean`	Whether the scroll area is at the right
`hasOverflowX`	`boolean`	Whether the scroll area has horizontal overflow
`hasOverflowY`	`boolean`	Whether the scroll area has vertical overflow
`getScrollProgress`	`() => Point`	Get the scroll progress as values between 0 and 1
`scrollToEdge`	`(details: ScrollToEdgeDetails) => void`	Scroll to the edge of the scroll area
`scrollTo`	`(details: ScrollToDetails) => void`	Scroll to specific coordinates
`getScrollbarState`	`(props: ScrollbarProps) => ScrollbarState`	Returns the state of the scrollbar

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>

Scroll Area

Features

Installation

Examples

Horizontal Scroll

Both Directions

API Reference

scrollArea.root

Rendered data attributes

scrollArea.viewport

Rendered data attributes

scrollArea.content

Rendered data attributes

scrollArea.scrollbar

Rendered data attributes

scrollArea.thumb

Rendered data attributes

Machine JavaScript API

Anatomy

On this page