docs/extension-test-page
What's New

Scroller

Storybook GitHub

A virtualized list that renders only what's visible, so large datasets scroll without slowing down the page.

Preview

Usage

You have a long list and need it to stay fast. Think of it like lazy loading for list items: instead of loading every item on the page at once, it will render only those currently visible. Scroll down, old items are removed from the DOM, new ones take their place. A list of 10,000 items performs the same as a list of 10.

If your list is short or already renders quickly without it, you don't need this component.

  • Fixed height (default): All items must be the same height. Provide :item-size in pixels. Scroll position is calculated with simple math — best performance for uniform lists (contacts, search results, menu items).

  • Variable height (dynamic): Items can grow to fit their content. Provide :min-item-size as an initial estimate; the component measures each item with ResizeObserver after render and adjusts accordingly. Use for content-driven layouts like chat threads or feeds.

The rule of thumb: if every item in your list is the same height, use fixed. If heights depend on the content inside, use dynamic.

Variants

Fixed height items

Use when all items share a known, uniform height. Set :item-size to that height in pixels.

Variable height items

Use when item heights depend on their content. Set dynamic="true" and :min-item-size to the smallest expected item height — the component measures actual sizes after render.

Direction

Defaults to vertical. Set to horizontal for a horizontal scroller.

Vue API 

import { DtScroller } from '@dialpad/dialtone-vue';

Slots

Name
Type
default

Props

Name
Default
Type
items required
array

The items to render. If the items are simple arrays, the index will be used as the key. If the items are objects, the keyField will be used as the key.

direction
'vertical'
"vertical" | "horizontal"

The direction of the scroller.

dynamic
false
"true" | "false"

Indicates if the items need to react to changes in their size. If disabled the itemSize prop is required and you will get improved performance. If enabled the minItemSize prop is required and you will have reduced performance but the ability to reactively size list items

itemSize
null
number

Display height (or width in horizontal mode) of the items in pixels used to calculate the scroll size and position. Required if DYNAMIC is false

itemTag
'div'
string

The tag to use for the items.

keyField
'id'
string

The key field to use for the items. If the items are objects, the scroller needs to be able to identify them. By default it will look for an id field on the items. This can be configured with this prop if you are using another field name.

listTag
'div'
string

The tag to use for the list.

minItemSize
null
number|string

Minimum size used if the height (or width in horizontal mode) of a item is unknown. Is required for the initial render of items in DYNAMIC size mode.

scrollerHeight
'100%'
string|number

The height of the scroller. Can be a number (in pixels) or a string (in CSS units).

scrollerWidth
'100%'
string|number

The width of the scroller. Can be a number (in pixels) or a string (in CSS units).

Events

Name
Type
user-position

Describe when the scroller changes from start/middle/end

Scroller documentation last updated Thursday, June 18, 2026