Scrolling

API for scrolling

API reference for Angular CDK scrolling

import {ScrollDispatchModule} from '@angular/cdk/scrolling';

Service contained all registered Scrollable references and emits an event when any one of the Scrollable references emit a scrolled event.

Properties
Name Description

scrollContainers: Map<CdkScrollable, Subscription>

Map of all the scrollable references that are registered with the service and their scroll event subscriptions.
Methods
ancestorScrolled

Returns an observable that emits whenever any of the scrollable ancestors of an element are scrolled.
Parameters

elementRef

ElementRef<any>

Element whose ancestors to listen for.

auditTimeInMs?

number

Time to throttle the scroll events.
Returns
Observable<CdkScrollable | void>

deregister

Deregisters a Scrollable reference and unsubscribes from its scroll event observable.
Parameters

scrollable

CdkScrollable

Scrollable instance to be deregistered.
getAncestorScrollContainers

Returns all registered Scrollables that contain the provided element.
Parameters

elementRef

ElementRef<any>

Returns
CdkScrollable[]

register

Registers a scrollable instance with the service and listens for its scrolled events. When the scrollable is scrolled, the service emits the event to its scrolled observable.
Parameters

scrollable

CdkScrollable

Scrollable instance to be registered.
scrolled

Returns an observable that emits an event whenever any of the registered Scrollable references (or window, document, or body) fire a scrolled event. Can provide a time in ms to override the default "throttle" time.

Note: in order to avoid hitting change detection for every scroll event, all of the events emitted from this stream will be run outside the Angular zone. If you need to update any data bindings as a result of a scroll event, you have to run the callback using NgZone.run.
Parameters

auditTimeInMs

number = DEFAULT_SCROLL_TIME

Returns
Observable<CdkScrollable | void>

Sends an event when the directive's element is scrolled. Registers itself with the ScrollDispatcher service to include itself as part of its collection of scrolling events that it can be listened to through the service.

Selector: [cdk-scrollable] [cdkScrollable]

Properties
Name Description

dir: Directionality

elementRef: ElementRef<HTMLElement>

ngZone: NgZone

scrollDispatcher: ScrollDispatcher

Methods
elementScrolled

Returns observable that emits when a scroll event is fired on the host element.
Returns
Observable<Event>

getElementRef

Gets the ElementRef for the viewport.
Returns
ElementRef<HTMLElement>

measureScrollOffset

Measures the scroll offset relative to the specified edge of the viewport. This method can be used instead of directly checking scrollLeft or scrollTop, since browsers are not consistent about what scrollLeft means in RTL. The values returned by this method are normalized such that left and right always refer to the left and right side of the scrolling container irrespective of the layout direction. start and end refer to left and right in an LTR context and vice-versa in an RTL context.
Parameters

from

"top" | "bottom" | "start" | "end" | "left" | "right"

The edge to measure from.
Returns
number

scrollTo

Scrolls to the specified offsets. This is a normalized version of the browser's native scrollTo method, since browsers are not consistent about what scrollLeft means in RTL. For this method left and right always refer to the left and right side of the scrolling container irrespective of the layout direction. start and end refer to left and right in an LTR context and vice-versa in an RTL context.
Parameters

options

ExtendedScrollToOptions

specified the offsets to scroll to.

A virtual scroll strategy that supports fixed-size items.

Selector: cdk-virtual-scroll-viewport[itemSize]

Properties
Name Description
@Input()

itemSize: number

The size of the items in the list (in pixels).
@Input()

maxBufferPx: number

The number of pixels worth of buffer to render for when rendering new items. Defaults to 200px.
@Input()

minBufferPx: number

The minimum amount of buffer rendered beyond the viewport (in pixels). If the amount of buffer dips below this number, more items will be rendered. Defaults to 100px.

A directive similar to ngForOf to be used for rendering data inside a virtual scrolling container.

Selector: [cdkVirtualFor][cdkVirtualForOf]

Properties
Name Description
@Input()

cdkVirtualForOf: DataSource<T> | Observable<T[]> | NgIterable<T>

The DataSource to display.
@Input()

cdkVirtualForTemplate: TemplateRef<CdkVirtualForOfContext<T>>

The template used to stamp out new elements.
@Input()

cdkVirtualForTemplateCacheSize: number

The size of the cache used to store templates that are not being used for re-use later. Setting the cache size to 0 will disable caching. Defaults to 20 templates.
@Input()

cdkVirtualForTrackBy: TrackByFunction<T> | undefined

The TrackByFunction to use for tracking changes. The TrackByFunction takes the index and the item and produces a value to be used as the item's identity when tracking changes.

dataStream: Observable<T[] | ReadonlyArray<T>>

Emits whenever the data in the current DataSource changes.

viewChange: Subject<ListRange>

Emits when the rendered view of the data changes.
Methods
measureRangeSize

Measures the combined size (width for horizontal orientation, height for vertical) of all items in the specified range. Throws an error if the range includes items that are not currently rendered.
Parameters

range

ListRange

orientation

"vertical" | "horizontal"

Returns
number

A viewport that virtualizes it's scrolling with the help of CdkVirtualForOf.

Selector: cdk-virtual-scroll-viewport

Properties
Name Description
@Input()

orientation: 'horizontal' | 'vertical'

The direction the viewport scrolls.
@Output()

scrolledIndexChange: Observable<number>

Emits when the index of the first element visible in the viewport changes.

dir: Directionality

elementRef: ElementRef<HTMLElement>

ngZone: NgZone

renderedRangeStream: Observable<ListRange>

A stream that emits whenever the rendered range changes.

scrollDispatcher: ScrollDispatcher

Methods
attach

Attaches a CdkVirtualForOf to this viewport.
Parameters

forOf

CdkVirtualForOf<any>

checkViewportSize

Update the viewport dimensions and re-render.
detach

Detaches the current CdkVirtualForOf.
elementScrolled

Returns observable that emits when a scroll event is fired on the host element.
Returns
Observable<Event>

getDataLength

Gets the length of the data bound to this viewport (in number of items).
Returns
number

getElementRef

Gets the ElementRef for the viewport.
Returns
ElementRef<HTMLElement>

getOffsetToRenderedContentStart

Gets the offset from the start of the viewport to the start of the rendered data (in pixels).
Returns
number | null

getRenderedRange

Get the current rendered range of items.
Returns
ListRange

getViewportSize

Gets the size of the viewport (in pixels).
Returns
number

measureRangeSize

Measure the total combined size of the given range. Throws if the range includes items that are not rendered.
Parameters

range

ListRange

Returns
number

measureRenderedContentSize

Measure the combined size of all of the rendered items.
Returns
number

measureScrollOffset

Gets the current scroll offset from the start of the viewport (in pixels).
Parameters

from?

"top" | "bottom" | "start" | "end" | "left" | "right"

The edge to measure the offset from. Defaults to 'top' in vertical mode and 'start' in horizontal mode.
Returns
number

scrollTo

Scrolls to the specified offsets. This is a normalized version of the browser's native scrollTo method, since browsers are not consistent about what scrollLeft means in RTL. For this method left and right always refer to the left and right side of the scrolling container irrespective of the layout direction. start and end refer to left and right in an LTR context and vice-versa in an RTL context.
Parameters

options

ExtendedScrollToOptions

specified the offsets to scroll to.
scrollToIndex

Scrolls to the offset for the given index.
Parameters

index

number

The index of the element to scroll to.

behavior

ScrollBehavior = 'auto'

The ScrollBehavior to use when scrolling. Default is behavior is auto.
scrollToOffset

Scrolls to the given offset from the start of the viewport. Please note that this is not always the same as setting scrollTop or scrollLeft. In a horizontal viewport with right-to-left direction, this would be the equivalent of setting a fictional scrollRight property.
Parameters

offset

number

The offset to scroll to.

behavior

ScrollBehavior = 'auto'

The ScrollBehavior to use when scrolling. Default is behavior is auto.
setRenderedContentOffset

Sets the offset from the start of the viewport to either the start or end of the rendered data (in pixels).
Parameters

offset

number

to

"to-start" | "to-end" = 'to-start'

setRenderedRange

Sets the currently rendered range of indices.
Parameters

range

ListRange

setTotalContentSize

Sets the total size of all content (in pixels), including content that is not currently rendered.
Parameters

size

number

Virtual scrolling strategy for lists with items of known fixed size.

Methods
attach

Attaches this scroll strategy to a viewport.
Parameters

viewport

CdkVirtualScrollViewport

The viewport to attach this strategy to.
detach

Detaches this scroll strategy from the currently attached viewport.
scrollToIndex

Scroll to the offset for the given index.
Parameters

index

number

The index of the element to scroll to.

behavior

ScrollBehavior

The ScrollBehavior to use when scrolling.
updateItemAndBufferSize

Update the item size and buffer size.
Parameters

itemSize

number

The size of the items in the virtually scrolling list.

minBufferPx

number

The minimum amount of buffer (in pixels) before needing to render more

maxBufferPx

number

The amount of buffer (in pixels) to render when rendering more.

Object that holds the scroll position of the viewport in each direction.

Properties
Name Description

left: number

top: number

A strategy that dictates which items should be rendered in the viewport.

Properties
Name Description

scrolledIndexChange: Observable<number>

Emits when the index of the first element visible in the viewport changes.
Methods
attach

Attaches this scroll strategy to a viewport.
Parameters

viewport

CdkVirtualScrollViewport

The viewport to attach this strategy to.
detach

Detaches this scroll strategy from the currently attached viewport.
onContentRendered

Called when the range of items rendered in the DOM has changed.
onContentScrolled

Called when the viewport is scrolled (debounced using requestAnimationFrame).
onDataLengthChanged

Called when the length of the data changes.
onRenderedOffsetChanged

Called when the offset of the rendered items changed.
scrollToIndex

Scroll to the offset for the given index.
Parameters

index

number

The index of the element to scroll to.

behavior

ScrollBehavior

The ScrollBehavior to use when scrolling.

An extended version of ScrollToOptions that allows expressing scroll offsets relative to the top, bottom, left, right, start, or end of the viewport rather than just the top and left. Please note: the top and bottom properties are mutually exclusive, as are the left, right, start, and end properties.

type ExtendedScrollToOptions = _XAxis & _YAxis & ScrollOptions;

The context for an item rendered by CdkVirtualForOf

type CdkVirtualForOfContext = {
    $implicit: T;
    cdkVirtualForOf: DataSource<T> | Observable<T[]> | NgIterable<T>;
    index: number;
    count: number;
    first: boolean;
    last: boolean;
    even: boolean;
    odd: boolean;
};

Time in ms to throttle the scrolling events by default.

const DEFAULT_SCROLL_TIME: 20;

Time in ms to throttle the resize events by default.

const DEFAULT_RESIZE_TIME: 20;

The injection token used to specify the virtual scrolling strategy.

const VIRTUAL_SCROLL_STRATEGY: InjectionToken<VirtualScrollStrategy>;