API reference for Angular CDK scrolling
import {ScrollingModule} from '@angular/cdk/scrolling';
Services
ScrollDispatcher
Service contained all registered Scrollable references and emits an event when any one of the Scrollable references emit a scrolled event.
Properties
Name | Description |
---|---|
|
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 | |
elementOrElementRef HTMLElement | ElementRef<any>
|
Element whose ancestors to listen for. |
auditTimeInMs? number
|
Time to throttle the scroll events. |
Returns | |
Observable<CdkScrollable | void>
|
|
deregister | |
---|---|
De-registers 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 | |
elementOrElementRef HTMLElement | 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 |
|
Parameters | |
auditTimeInMs number = DEFAULT_SCROLL_TIME
|
|
Returns | |
Observable<CdkScrollable | void>
|
|
Directives
CdkScrollable
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 |
---|---|
|
|
|
|
|
|
|
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. |
CdkFixedSizeVirtualScroll
A virtual scroll strategy that supports fixed-size items.
Selector: cdk-virtual-scroll-viewport[itemSize]
Properties
Name | Description |
---|---|
@Input()
|
The size of the items in the list (in pixels). |
@Input()
|
The number of pixels worth of buffer to render for when rendering new items. Defaults to 200px. |
@Input()
|
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. |
CdkVirtualForOf
A directive similar to ngForOf
to be used for rendering data inside a virtual scrolling
container.
Selector: [cdkVirtualFor][cdkVirtualForOf]
Properties
Name | Description |
---|---|
@Input()
|
The DataSource to display. |
@Input()
|
The template used to stamp out new elements. |
@Input()
|
The size of the cache used to store templates that are not being used for re-use later.
Setting the cache size to |
@Input()
|
The |
|
Emits whenever the data in the current DataSource changes. |
|
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 "horizontal" | "vertical"
|
|
Returns | |
number
|
|
static
ngTemplateContextGuard
|
|
---|---|
Parameters | |
directive CdkVirtualForOf<T>
|
|
context unknown
|
|
Returns | |
context is CdkVirtualForOfContext<T>
|
|
CdkVirtualScrollViewport
extends
CdkVirtualScrollable
A viewport that virtualizes its scrolling with the help of CdkVirtualForOf
.
Selector: cdk-virtual-scroll-viewport
Properties
Name | Description |
---|---|
@Input({ transform: booleanAttribute })
|
Whether rendered items should persist in the DOM after scrolling out of view. By default, items will be removed. |
@Input()
|
The direction the viewport scrolls. |
@Output()
|
Emits when the index of the first element visible in the viewport changes. |
|
|
|
A stream that emits whenever the rendered range changes. |
|
Methods
attach | |
---|---|
Attaches a |
|
Parameters | |
forOf CdkVirtualScrollRepeater<any>
|
|
checkViewportSize | |
---|---|
Update the viewport dimensions and re-render. |
detach | |
---|---|
Detaches the current |
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
|
|
measureBoundingClientRectWithScrollOffset | |
---|---|
Parameters | |
from "top" | "bottom" | "left" | "right"
|
|
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 scrollable (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
|
|
measureViewportOffset | |
---|---|
Measures the offset of the viewport from the scrolling container |
|
Parameters | |
from? "top" | "bottom" | "start" | "end" | "left" | "right"
|
The edge to measure from. |
measureViewportSize | |
---|---|
Measure the viewport size for the provided orientation. |
|
Parameters | |
orientation "horizontal" | "vertical"
|
The orientation to measure the size from. |
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 |
scrollToOffset | |
---|---|
Scrolls to the given offset from the start of the viewport. Please note that this is not always
the same as setting |
|
Parameters | |
offset number
|
The offset to scroll to. |
behavior ScrollBehavior = 'auto'
|
The ScrollBehavior to use when scrolling. Default is behavior is |
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
|
|
CdkVirtualScrollableElement
extends
CdkVirtualScrollable
Provides a virtual scrollable for the element it is attached to.
Selector: [cdkVirtualScrollingElement]
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>
|
|
measureBoundingClientRectWithScrollOffset | |
---|---|
Parameters | |
from "top" | "bottom" | "left" | "right"
|
|
Returns | |
number
|
|
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
|
|
measureViewportSize | |
---|---|
Measure the viewport size for the provided orientation. |
|
Parameters | |
orientation "horizontal" | "vertical"
|
The orientation to measure the size from. |
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. |
CdkVirtualScrollableWindow
extends
CdkVirtualScrollable
Provides as virtual scrollable for the global / window scrollbar.
Selector: cdk-virtual-scroll-viewport[scrollWindow]
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>
|
|
measureBoundingClientRectWithScrollOffset | |
---|---|
Parameters | |
from "top" | "bottom" | "left" | "right"
|
|
Returns | |
number
|
|
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
|
|
measureViewportSize | |
---|---|
Measure the viewport size for the provided orientation. |
|
Parameters | |
orientation "horizontal" | "vertical"
|
The orientation to measure the size from. |
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. |
Classes
FixedSizeVirtualScrollStrategy
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. |
CdkVirtualScrollable
extends
CdkScrollable
Extending the {@link CdkScrollable} to be used as scrolling container for virtual scrolling.
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>
|
|
measureBoundingClientRectWithScrollOffset | |
---|---|
Measure the bounding DOMRect size including the scroll offset. |
|
Parameters | |
from "top" | "bottom" | "left" | "right"
|
The edge to measure from. |
Returns | |
number
|
|
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
|
|
measureViewportSize | |
---|---|
Measure the viewport size for the provided orientation. |
|
Parameters | |
orientation "horizontal" | "vertical"
|
The orientation to measure the size from. |
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. |
Interfaces
ViewportScrollPosition
Object that holds the scroll position of the viewport in each direction.
Properties
Name | Description |
---|---|
|
|
|
VirtualScrollStrategy
A strategy that dictates which items should be rendered in the viewport.
Properties
Name | Description |
---|---|
|
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. |
CdkVirtualScrollRepeater
An item to be repeated by the VirtualScrollViewport
Properties
Name | Description |
---|---|
|
Methods
measureRangeSize | |
---|---|
Parameters | |
range ListRange
|
|
orientation "horizontal" | "vertical"
|
|
Returns | |
number
|
|
Type aliases
ExtendedScrollToOptions
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;
CdkVirtualForOfContext
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;
};
Constants
DEFAULT_SCROLL_TIME
Time in ms to throttle the scrolling events by default.
const DEFAULT_SCROLL_TIME: 20;
DEFAULT_RESIZE_TIME
Time in ms to throttle the resize events by default.
const DEFAULT_RESIZE_TIME: 20;
VIRTUAL_SCROLL_STRATEGY
The injection token used to specify the virtual scrolling strategy.
const VIRTUAL_SCROLL_STRATEGY: InjectionToken<VirtualScrollStrategy>;
VIRTUAL_SCROLLABLE
const VIRTUAL_SCROLLABLE: InjectionToken<CdkVirtualScrollable>;