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>

Features

Native browser scrolling
Supports vertical and horizontal scrolling
Customizable scrollbar appearance
Scrollbar visible always, while scrolling or on hover
Scrollbar thumb follows the scroll position

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>

Installation

typo3 ui:add scrollArea

Read more about installing Components and Primitives.

Examples

Scroll horizontally

Add a horizontal scrollbar for wide content, like a row of product cards.

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>

Scroll in both directions

Add one scrollbar per orientation for content that is wider and taller than the area, like a large table.

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.

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`rootId`	`string` The root ID of the component, used for hydration and identification.	No	-
`ids`	`array` The IDs of of the component parts for composition.	No	[]
`autoMount`	`boolean` Whether the client initializes the component on its own. Set it to false to mount it yourself with `mount()`	No	true
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-scroll-area-root`	<uid>
`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.

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-scroll-area-viewport`	<uid>
`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.

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-scroll-area-content`	<uid>
`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
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-scroll-area-scrollbar`	<uid>
`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.

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-scroll-area-thumb`	<uid>
`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
`getCornerState`	`() => CornerState`	Returns the state of the corner