ui/VirtualList

Edit on GitHub

Unstyled virtual list components and behaviors to be customized by a theme or application.

Members

VirtualList Component

An unstyled scrollable virtual list component with touch support.

Extends: ui/VirtualListui/VirtualList.VirtualListBasic

Properties

cbScrollTo

Function

A callback function that receives a reference to the scrollTo feature.

Once received, the scrollTo method can be called as an imperative interface.

The scrollTo function accepts the following parameters:

{position: {x, y}} - Pixel value for x and/or y position
{align} - Where the scroll area should be aligned. Values are: 'left', 'right', 'top', 'bottom', 'topleft', 'topright', 'bottomleft', and 'bottomright'.
{index} - Index of specific item. (0 or positive integer) This option is available for only VirtualList kind.
{node} - Node to scroll into view
{animate} - When true, scroll occurs with animation. When false, no animation occurs.
{focus} - When true, attempts to focus item after scroll. Only valid when scrolling by index or node.

Note: Only specify one of: position, align, index or node

Example:

// If you set cbScrollTo prop like below;
cbScrollTo: (fn) => {this.scrollTo = fn;}
// You can simply call like below;
this.scrollTo({align: 'top'}); // scroll to the top

direction

String

The layout direction of the list.

Valid values are:

'horizontal', and
'vertical'.

Default: 'vertical'

horizontalScrollbar

String

Specifies how to show horizontal scrollbar.

Valid values are:

'auto',
'visible', and
'hidden'.

Default: 'auto'

noScrollByWheel

Boolean

Prevents scroll by wheeling on the list.

Default: false

onScroll

Function

Called when scrolling.

Passes scrollLeft, scrollTop, and moreInfo. It is not recommended to set this prop since it can cause performance degradation. Use onScrollStart or onScrollStop instead.

onScrollStart

Function

Called when scroll starts.

Passes scrollLeft, scrollTop, and moreInfo. You can get firstVisibleIndex and lastVisibleIndex from VirtualList with moreInfo.

Example:

onScrollStart = ({scrollLeft, scrollTop, moreInfo}) => {
    const {firstVisibleIndex, lastVisibleIndex} = moreInfo;
    // do something with firstVisibleIndex and lastVisibleIndex
}

render = () => (
    <VirtualList
        ...
        onScrollStart={this.onScrollStart}
        ...
    />
)

onScrollStop

Function

Called when scroll stops.

Passes scrollLeft, scrollTop, and moreInfo. You can get firstVisibleIndex and lastVisibleIndex from VirtualList with moreInfo.

Example:

onScrollStop = ({scrollLeft, scrollTop, moreInfo}) => {
    const {firstVisibleIndex, lastVisibleIndex} = moreInfo;
    // do something with firstVisibleIndex and lastVisibleIndex
}

render = () => (
    <VirtualList
        ...
        onScrollStop={this.onScrollStop}
        ...
    />
)

role

String

The ARIA role for the list.

Default: 'list'

scrollMode

String

Specifies how to scroll.

Valid values are:

'translate',
'native'.

Default: 'translate'

verticalScrollbar

String

Specifies how to show vertical scrollbar.

Valid values are:

'auto',
'visible', and
'hidden'.

Default: 'auto'

VirtualGridList Component

An unstyled scrollable virtual grid list component with touch support.

Extends: ui/VirtualListui/VirtualList.VirtualListBasic

Properties

cbScrollTo

Function

A callback function that receives a reference to the scrollTo feature.

Once received, the scrollTo method can be called as an imperative interface.

The scrollTo function accepts the following parameters:

{position: {x, y}} - Pixel value for x and/or y position
{align} - Where the scroll area should be aligned. Values are: 'left', 'right', 'top', 'bottom', 'topleft', 'topright', 'bottomleft', and 'bottomright'.
{index} - Index of specific item. (0 or positive integer) This option is available for only VirtualList kind.
{node} - Node to scroll into view
{animate} - When true, scroll occurs with animation. When false, no animation occurs.
{focus} - When true, attempts to focus item after scroll. Only valid when scrolling by index or node.

Note: Only specify one of: position, align, index or node

Example:

// If you set cbScrollTo prop like below;
cbScrollTo: (fn) => {this.scrollTo = fn;}
// You can simply call like below;
this.scrollTo({align: 'top'}); // scroll to the top

direction

String

The layout direction of the list.

Valid values are:

'horizontal', and
'vertical'.

Default: 'vertical'

horizontalScrollbar

String

Specifies how to show horizontal scrollbar.

Valid values are:

'auto',
'visible', and
'hidden'.

Default: 'auto'

noScrollByWheel

Boolean

Prevents scroll by wheeling on the list.

Default: false

onScroll

Function

Called when scrolling.

Passes scrollLeft, scrollTop, and moreInfo. It is not recommended to set this prop since it can cause performance degradation. Use onScrollStart or onScrollStop instead.

onScrollStart

Function

Called when scroll starts.

Passes scrollLeft, scrollTop, and moreInfo. You can get firstVisibleIndex and lastVisibleIndex from VirtualGridList with moreInfo.

Example:

onScrollStart = ({scrollLeft, scrollTop, moreInfo}) => {
    const {firstVisibleIndex, lastVisibleIndex} = moreInfo;
    // do something with firstVisibleIndex and lastVisibleIndex
}

render = () => (
    <VirtualGridList
        ...
        onScrollStart={this.onScrollStart}
        ...
    />
)

onScrollStop

Function

Called when scroll stops.

Passes scrollLeft, scrollTop, and moreInfo. You can get firstVisibleIndex and lastVisibleIndex from VirtualList with moreInfo.

Example:

onScrollStop = ({scrollLeft, scrollTop, moreInfo}) => {
    const {firstVisibleIndex, lastVisibleIndex} = moreInfo;
    // do something with firstVisibleIndex and lastVisibleIndex
}

render = () => (
    <VirtualGridList
        ...
        onScrollStop={this.onScrollStop}
        ...
    />
)

role

String

The ARIA role for the list.

Default: 'list'

scrollMode

String

Specifies how to scroll.

Valid values are:

'translate',
'native'.

Default: 'translate'

verticalScrollbar

String

Specifies how to show vertical scrollbar.

Valid values are:

'auto',
'visible', and
'hidden'.

Default: 'auto'

VirtualListBasic Component

A basic base component for ui/VirtualListui/VirtualList.VirtualList and ui/VirtualListui/VirtualList.VirtualGridList.

Properties

Required Property • itemRenderer

Function

The rendering function called for each item in the list.

Note: The list does not always render a component whenever its render function is called due to performance optimization.

Example:

renderItem = ({index, ...rest}) => {

	return (
		<MyComponent index={index} {...rest} />
	);
}

childProps

Object

Additional props included in the object passed to the itemRenderer callback.

clientSize

Object

Client size of the list; valid values are an object that has clientWidth and clientHeight.

dataSize

Number

The number of items of data the list contains.

Default: 0

direction

String

The layout direction of the list.

Valid values are:

'horizontal', and
'vertical'.

Default: 'vertical'

role

String

The ARIA role for the list.

Default: 'list'

scrollMode

String

Specifies how to scroll.

Valid values are:

'translate',
'native'.

Default: 'translate'

spacing

Number

The spacing between items.

Default: 0

Type Definitions

gridListItemSizeShape Object

The shape for the grid list item size in a list for ui/VirtualListui/VirtualList.VirtualGridList.

• minWidth

Number

The minimum width of the grid list item.

• minHeight

Number

The minimum height of the grid list item.

itemSizesShape Object

The shape for the list different item size in a list for ui/VirtualListui/VirtualList.VirtualList.

• minSize

Number

The minimum size of the list item.

• size

Array(Number)

An array of the list item size. If it is not defined, the list items will render with the minSize size.