Scroll Area

updated

Scrollbars that don't look like Windows 98. Custom bars over a native scroller, with optional virtualization.

Demo

Line 1

Line 2

Line 3

Line 4

Line 5

Line 6

Line 7

Line 8

Line 9

Line 10

Line 11

Line 12

Line 13

Line 14

Line 15

Line 16

Line 17

Line 18

Line 19

Line 20

Line 21

Line 22

Line 23

Line 24

Line 25

Line 26

Line 27

Line 28

Line 29

Line 30

Installation

Usage

<script setup lang="ts">
import { ScrollArea } from '@/components/ui/scroll-area'
</script>

<template>
  <ScrollArea class="h-72 rounded-lg border">
    <div class="p-4">…</div>
  </ScrollArea>
</template>

ScrollArea sizes from its content and scrolls once you bound it: h-*, max-h-*, flex-1 in a column, a grid row, h-full. Without a bound it shows everything, like a div.

The scrolling stays native. Only the scrollbar is custom. On touch screens, the bars only show where you are, and touches go straight to the content.

Examples

Inside a Card

With max-h-48, the body grows with its content and starts scrolling at 192px, while the header and footer stay in view.

In a card

Activity

The latest builds on main.

  • Build #1240 passed2 min ago
  • Build #1239 passed3 min ago
  • Build #1238 passed4 min ago
  • Build #1237 passed5 min ago
  • Build #1236 passed6 min ago
  • Build #1235 passed7 min ago
  • Build #1234 passed8 min ago
  • Build #1233 passed9 min ago
  • Build #1232 passed10 min ago
  • Build #1231 passed11 min ago
  • Build #1230 passed12 min ago
  • Build #1229 passed13 min ago
  • Build #1228 passed14 min ago
  • Build #1227 passed15 min ago
  • Build #1226 passed16 min ago
  • Build #1225 passed17 min ago
  • Build #1224 passed18 min ago
  • Build #1223 passed19 min ago
  • Build #1222 passed20 min ago
  • Build #1221 passed21 min ago
  • Build #1220 passed22 min ago
  • Build #1219 passed23 min ago
  • Build #1218 passed24 min ago
  • Build #1217 passed25 min ago
24 builds today

Always visible

visible forces the bars on or off. delay sets how long they stay after scrolling stops. While they're shown, the root has data-active.

Scroll area, always visible

Always visible. Line 1

Always visible. Line 2

Always visible. Line 3

Always visible. Line 4

Always visible. Line 5

Always visible. Line 6

Always visible. Line 7

Always visible. Line 8

Always visible. Line 9

Always visible. Line 10

Always visible. Line 11

Always visible. Line 12

Always visible. Line 13

Always visible. Line 14

Always visible. Line 15

Always visible. Line 16

Always visible. Line 17

Always visible. Line 18

Always visible. Line 19

Always visible. Line 20

Always visible. Line 21

Always visible. Line 22

Always visible. Line 23

Always visible. Line 24

Always visible. Line 25

Always visible. Line 26

Always visible. Line 27

Always visible. Line 28

Always visible. Line 29

Always visible. Line 30

Offsets

Offsets

Inset bar. Line 1

Inset bar. Line 2

Inset bar. Line 3

Inset bar. Line 4

Inset bar. Line 5

Inset bar. Line 6

Inset bar. Line 7

Inset bar. Line 8

Inset bar. Line 9

Inset bar. Line 10

Inset bar. Line 11

Inset bar. Line 12

Inset bar. Line 13

Inset bar. Line 14

Inset bar. Line 15

Inset bar. Line 16

Inset bar. Line 17

Inset bar. Line 18

Inset bar. Line 19

Inset bar. Line 20

Inset bar. Line 21

Inset bar. Line 22

Inset bar. Line 23

Inset bar. Line 24

Inset bar. Line 25

Inset bar. Line 26

Inset bar. Line 27

Inset bar. Line 28

Inset bar. Line 29

Inset bar. Line 30

Styling

The bar is its own component, ScrollBar, with its own class. The thumb's look lives in your copy of ScrollBar.vue, so edit it there. You can also reach any part from the root's class through data-slot and data-axis:

Styling

Restyled thumb. Line 1

Restyled thumb. Line 2

Restyled thumb. Line 3

Restyled thumb. Line 4

Restyled thumb. Line 5

Restyled thumb. Line 6

Restyled thumb. Line 7

Restyled thumb. Line 8

Restyled thumb. Line 9

Restyled thumb. Line 10

Restyled thumb. Line 11

Restyled thumb. Line 12

Restyled thumb. Line 13

Restyled thumb. Line 14

Restyled thumb. Line 15

Restyled thumb. Line 16

Restyled thumb. Line 17

Restyled thumb. Line 18

Restyled thumb. Line 19

Restyled thumb. Line 20

Restyled thumb. Line 21

Restyled thumb. Line 22

Restyled thumb. Line 23

Restyled thumb. Line 24

Restyled thumb. Line 25

Restyled thumb. Line 26

Restyled thumb. Line 27

Restyled thumb. Line 28

Restyled thumb. Line 29

Restyled thumb. Line 30

Horizontal

orientation is vertical by default, horizontal, or both. A vertical area won't scroll sideways, so content that overflows horizontally needs horizontal or both. Right-to-left is mirrored either way.

A vertical area gives its content the area's width, so truncate, line-clamp-* and percentage widths work inside it as they do anywhere else. With horizontal or both, the content grows to its longest line instead, and a part that must stay narrower needs a width of its own.

Horizontal scroll area
1
2
3
4
5
6
7
8
9
10
11
12

Both axes

orientation="both" draws two bars that meet in the corner. To keep the corner free, use verticalOffset and horizontalOffset. With virtualize, only the rows are virtualized, unless you add columns.

On both axes
1:1
1:2
1:3
1:4
1:5
1:6
1:7
1:8
1:9
1:10
1:11
1:12
2:1
2:2
2:3
2:4
2:5
2:6
2:7
2:8
2:9
2:10
2:11
2:12
3:1
3:2
3:3
3:4
3:5
3:6
3:7
3:8
3:9
3:10
3:11
3:12
4:1
4:2
4:3
4:4
4:5
4:6
4:7
4:8
4:9
4:10
4:11
4:12
5:1
5:2
5:3
5:4
5:5
5:6
5:7
5:8
5:9
5:10
5:11
5:12
6:1
6:2
6:3
6:4
6:5
6:6
6:7
6:8
6:9
6:10
6:11
6:12
7:1
7:2
7:3
7:4
7:5
7:6
7:7
7:8
7:9
7:10
7:11
7:12
8:1
8:2
8:3
8:4
8:5
8:6
8:7
8:8
8:9
8:10
8:11
8:12
9:1
9:2
9:3
9:4
9:5
9:6
9:7
9:8
9:9
9:10
9:11
9:12
10:1
10:2
10:3
10:4
10:5
10:6
10:7
10:8
10:9
10:10
10:11
10:12
11:1
11:2
11:3
11:4
11:5
11:6
11:7
11:8
11:9
11:10
11:11
11:12
12:1
12:2
12:3
12:4
12:5
12:6
12:7
12:8
12:9
12:10
12:11
12:12

Edge fade

While the area can still scroll towards an edge, the root has data-overflow-x-start, -x-end, -y-start or -y-end. Pair it with scroll-fade-overlay-x for gradients, or show controls with group-has-[[data-overflow-x-end]]. No scroll listeners needed.

The buttons in the demo scroll by 80% of the width with setScrollPosition.

Edge fade
AllDesignEngineeringProductMarketingSalesSupportFinanceLegalPeopleResearchDataSecurityOperationsGrowthContentBrandPartnershipsCommunityEvents

Edge events

reachEdge fires once when you scroll into an edge zone, with { edge, ref }, and again only after you leave it. edgeOffset widens the zone in pixels. Want to load more on reach? That's Infinite Scroll, which ships with this component.

Edge events

Line 1

Line 2

Line 3

Line 4

Line 5

Line 6

Line 7

Line 8

Line 9

Line 10

Line 11

Line 12

Line 13

Line 14

Line 15

Line 16

Line 17

Line 18

Line 19

Line 20

Line 21

Line 22

Line 23

Line 24

Line 25

Line 26

Line 27

Line 28

Line 29

Line 30

Scroll to an edge.

Virtualize

10,000 rows, 20 in the DOM. Set virtualize and pass items, and the default slot renders only what's on screen (plus a small buffer), with { item, index }.

virtualize needs a bound: h-*, max-h-*, or a flex or grid parent that sizes the area. The list scrolls inside the area, so without one the area grows to the whole list and renders every item; in development it warns once.

estimateSize is just a guess: real sizes are measured after render, so items can have different heights. It runs on TanStack Virtual, which is why it installs @tanstack/vue-virtual.

Virtualized scroll area

Horizontal virtualize

A horizontal list needs a height: its items are positioned across the strip, so they can't give it one.

Horizontal virtualized scroll area

Masonry

Pinterest at home. lanes and gap turn the list into a masonry grid.

Masonry scroll area

Grid

A spreadsheet's worth of cells. With orientation="both", columns in virtualize virtualizes the columns as well as the rows, and the default slot renders once per visible cell with { item, index, column }. item and index are the row's; column is { index, start, size }.

Column widths start from columns.estimateSize, a number or a function of the index. A cell is never narrower than its column, and one with wider content widens the whole column. scrollToColumn(index, edge?) scrolls sideways the way scrollTo scrolls down.

Without columns, rows wider than the area still scroll sideways, but nothing measures their width, so there's no horizontal bar and no data-overflow-x-*.

Grid scroll area

Programmatic scroll

scrollTo(index, edge?) scrolls to an item. Pass 'start', 'center' or 'end' to align it; leave edge out, and an already visible item stays where it is.

@virtual-scroll fires with { index, from, to, direction, ref } whenever the item at the scroll position changes.

Without items, setScrollPosition(axis, offset, duration?) and setScrollPercentage(axis, fraction, duration?) scroll by pixels or by a fraction of the way. Both measure the content when called, so after you append a message and await nextTick(), setScrollPercentage('vertical', 1) lands on the new end.

Scroll area, programmatic scroll

setScrollPositionSilently(axis, offset) jumps at once and emits nothing for that move: no scroll, reachEdge or virtualScroll, and the bar doesn't flash. Use it to put back a saved position without your handlers taking it for the user's scroll; it works right in onMounted, before a virtual list has attached to the viewport. Native scroll listeners still see the move, InfiniteScroll included.

Keys and anchoring

A chat loads older messages above the one you're reading. Rows are keyed by index, so a row added at the top shifts every row below it into its neighbour's element. Give virtualize a getItemKey, and each row keeps its element, its state and its measured size wherever it moves.

anchorTo: 'end' keeps the first visible row where it is when rows are added or removed at either end, and keeps a view that is at the end there while the last row grows, as a streamed reply does. Holding a row in place needs getItemKey. followOnAppend (true, or 'smooth' to animate) makes a view at the end follow rows appended below it.

Scroll area, keys and anchoring

Loading the older rows with InfiniteScroll? Pass the area's API as its target, so it leaves the position to the anchor instead of shifting it a second time.

External scroll element

Want to virtualize against a parent scroller, like the page itself? Pass getScrollElement and scrollMargin (the list's offset from the top of that scroller) to virtualize. The component then grows to the list's full size and draws no bars.

getScrollElement must return the element right at mount. If it returns null first and the element later, the list won't attach to anything.

Data you don't hold

Pass items-size and items-fn instead of items. The function is called with (from, size), only for what's on screen.

API Reference

Data attributes

data-slotAttributesDescription
scroll-areadata-active, data-orientation, data-overflow-x-start, data-overflow-x-end, data-overflow-y-start, data-overflow-y-endThe root. Each data-overflow attribute is present while the viewport can still scroll towards that edge; x-start is the right edge in right-to-left.
scroll-area-viewport—The native scroller. Receives tabindex.
scroll-area-contentdata-activeWraps the slot.
scroll-area-virtual—The sized container for virtual items.
scroll-area-itemdata-indexOne virtual item, or one row of a grid.
scroll-area-celldata-indexOne cell of a virtual grid, inside its row. data-index is the column's index.
scroll-area-bardata-axisThe track. Hidden from screen readers; lets touches through.
scroll-area-thumbdata-axisThe thumb, draggable with a mouse or pen. Hidden from screen readers; lets touches through.

Accessibility

tabindex goes to the viewport, the element that actually scrolls. Other attributes, aria-label included, go to the root, so a label names the wrapper, not the focusable element.

Once focused, the viewport scrolls with the keyboard:

KeyAction
↑ ↓ ← →Scrolls by a line on the active axis.
Page Up / Page DownScrolls by a page.
Home / EndScrolls to the start or the end.
SpaceScrolls down by a page; Shift+Space scrolls up.

Changelog

  1. registry 0.24.1

    35a5371 — No component styles an element through a :has() on its parent or group any more. Chrome restyles the whole subtree of every :has() anchor above a node that is added or removed, once some rule puts :has() away from the element it styles: a page wrapped in one such anchor recalculated every element for each list row it mounted. The Dialog, Drawer and Tour headers, the InputGroup and InputNumber insets, the Combobox clear button, the InputFloating notch, a FieldLabel beside a disabled checkbox or radio, the Rating ring, and the Slider and ScrollArea examples now read their neighbours with ~ or a :has() on the element itself. The InputGroup addons fade through a variable that the group sets. FileUpload, Image, Marquee and DataTable mark the state on an element instead: the hidden input's focus, an ImageError inside, keyboard focus, and the body above pinned bottom rows. scripts/has-selectors.test.ts keeps the pattern out.

    useSwipeSnap no longer flushes styles for an instant move that leaves the offset where it is, such as new points at rest.

  2. core 0.17.1

    35a5371 — No component styles an element through a :has() on its parent or group any more. Chrome restyles the whole subtree of every :has() anchor above a node that is added or removed, once some rule puts :has() away from the element it styles: a page wrapped in one such anchor recalculated every element for each list row it mounted. The Dialog, Drawer and Tour headers, the InputGroup and InputNumber insets, the Combobox clear button, the InputFloating notch, a FieldLabel beside a disabled checkbox or radio, the Rating ring, and the Slider and ScrollArea examples now read their neighbours with ~ or a :has() on the element itself. The InputGroup addons fade through a variable that the group sets. FileUpload, Image, Marquee and DataTable mark the state on an element instead: the hidden input's focus, an ImageError inside, keyboard focus, and the body above pinned bottom rows. scripts/has-selectors.test.ts keeps the pattern out.

    useSwipeSnap no longer flushes styles for an instant move that leaves the offset where it is, such as new points at rest.

  3. registry 0.23.0

    44fdc9a — ScrollArea: virtualize takes getItemKey, anchorTo and followOnAppend from TanStack Virtual. With getItemKey, rows are keyed by item instead of index, so a row keeps its element and measured size when rows arrive above it. anchorTo: 'end' keeps the first visible row in place as rows are added or removed at either end. followOnAppend makes a view at the end follow appended rows: a chat that loads older messages above and new ones below. The new setScrollPositionSilently(axis, offset) jumps without emitting scroll, reachEdge or virtualScroll, for restoring a saved position. Both setters now hold in onMounted on a virtual list, which TanStack used to scroll back to the top when it attached to the viewport a tick later. useInfiniteScroll with a ScrollArea API as its target no longer shifts a list anchored to the end a second time after loading above it.

  4. registry 0.22.1

    9398d0f — Item: a long title or description no longer pushes the content under the media or past the row's edge. ItemContent can shrink (min-w-0) and ItemTitle stops at its column (max-w-full), so line-clamp-1 on the title, or a truncate span inside it, cuts the text with an ellipsis.

  5. registry 0.22.0

    6784a5e — ScrollArea sizes from its content: max-h-*, flex-1 (with or without min-h-0), a grid row and auto height work, so a Card body or a chip strip needs no fixed height. A ScrollArea with no size now shows its content instead of collapsing, and virtualize without a bounded height or width warns once in development.

    Inside a ScrollArea, a Table's own sideways scrolling turns off, so a sticky TableHeader sticks to the area; give the ScrollArea orientation="both" when the table can be wider than it.

    37a2189 — ScrollArea virtualizes columns as well as rows (virtualize.columns), so a wide virtual grid gets a horizontal bar and data-overflow-x-*. The slot renders once per visible cell with { item, index, column }, and the exposed API gains scrollToColumn and columnVirtualizer.

    47435b2 — A wheel over a ScrollArea's bar or thumb scrolls the area instead of the page: the bar and thumb sit beside the viewport, outside its scroll chain, and now forward the wheel to it. At the area's edge the page still takes the wheel, and Ctrl+wheel still zooms.

    f75454e — In external-scroll mode (virtualize.getScrollElement), ScrollArea's getScrollTarget, setScrollPosition and setScrollPercentage act on the external scroller instead of the inner viewport, which never scrolls there, so a nested InfiniteScroll reads the right edge. getScroll and getScrollPosition still report the inner viewport in that mode.

    97eb8c2 — A virtualized ScrollArea given an inline virtualize object no longer re-measures on every parent render: equal options keep their resolved form, so the sizes measured above the viewport survive an unrelated update and the list stops jumping. A function estimateSize or getScrollElement written inline still counts as a change; hoist those.

    a751cf6 — ScrollArea measures its content in layout pixels, as it measures its viewport: under a scaled ancestor, and in a Dialog, Popover or Menu that opens with the default scale-in, the content was measured short for its whole life, so the thumb came out too long, the end fade dropped out and reachEdge fired early.

    288472a — Only a primary-button press on a ScrollArea's bar or thumb jumps or drags the content; a right or middle press no longer does.

  6. registry 0.21.0

    ad14b64 — SelectContent no longer renders SelectScrollUpButton and SelectScrollDownButton: a long list scrolls like any other instead of scrolling under the pointer as it hovers an arrow. Both parts stay exported, so a project that wants them puts them back around the viewport in its own SelectContent, or wraps the slot in a ScrollArea.

  7. registry 0.19.0

    264c758 — Item: size is the row's density, as in shadcn. It sets padding, gap and the media size (through --item-media on the root), and no longer scales the text of ItemTitle and ItemDescription, which stay at text-label-lg and text-body-md. The parts carry no group-data-[size=…] variants any more, so a class of your own, like text-body-sm, line-clamp-none or size-12 on an ItemMedia, wins.

    4ff76a9 — ScrollArea: a vertical area gives its content the area's width, so truncate, line-clamp-* and percentage widths work inside it. Before, the content box grew to the longest line, as in QScrollArea. horizontal and both keep letting the content grow.

    setScrollPercentage and setScrollPosition measure the viewport when called instead of reading the last observed size, so setScrollPercentage('vertical', 1) right after a content change reaches the new end.

  8. registry 0.16.0

    39324b3 — InfiniteScroll takes shouldLoad, the "time to load?" check useInfiniteScroll() already had: it gets the direction and replaces the offset check, and returning undefined falls back to offset.

  9. registry 0.9.0

    f4d7e8e — ScrollArea's scrollbar carries data-no-drag, so dragging its thumb with a mouse inside a Drawer scrolls instead of moving the drawer.

  10. registry 0.8.0

    c0234b2 — ScrollArea moves its thumb with transform instead of top / inset-inline-start, so scrolling no longer lays out and repaints the bar on every frame, and the thumb drops its permanent will-change layer.

  11. registry 0.5.0

    e931ebe — Add DataTable over TanStack Table v9: columns and data, per-column header and cell slots, sorting with an accessible header button, a scroll area with sticky header and footer, pinned columns with offsets from the width model, density and stripes, row events, client and manual pagination, loading and empty states, and row virtualization with one row group per row and exact spacers. Row selection with a checkbox column, shift-click ranges, a page and select-all banner and a source on update:rowSelection; expanding into detail rows and trees; grouping with aggregated cells; pinned rows in sticky row groups; infinite scroll through onLoadMore, hasMore and loadMore. The table styles gain rowGroup and pinnedRows, a sticky TableHeader and TableFooter read --table-sticky-top and --table-sticky-bottom for the offset under a fixed app bar, and useInfiniteScroll accepts a shouldLoad that returns undefined to fall back to the pixel check.

    9181705 — ScrollArea scrolls on both axes with orientation="both", emits reachEdge once per entry into an edge zone (edgeOffset widens it), and ships useInfiniteScroll and InfiniteScroll: loading on approach to any of four edges with a promise, 'stop' to end a direction, initial fill of the viewport and a kept reading position when content is prepended.

    5f82937 — ScrollArea's bars and thumbs let touches through on a touch screen (pointer: coarse), so a finger that lands on the bar scrolls the content natively instead of grabbing the thumb.