Enact
Edit on GitHub

ui/VirtualList

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

import VirtualList from '@enact/ui/VirtualList';

Members

VirtualListComponent

An unstyled scrollable virtual list component with touch support.

import VirtualList from '@enact/ui/VirtualList';
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'

VirtualGridListComponent

An unstyled scrollable virtual grid list component with touch support.

import {VirtualGridList} from '@enact/ui/VirtualList';
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'

VirtualListBaseComponent

A basic base component for VirtualList and VirtualGridList.

import {VirtualListBase} from '@enact/ui/VirtualList';
Properties
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}) => {
	delete rest.data;

	return (
		<MyComponent index={index} {...rest} />
	);
}
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
childProps
Object

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

clientSize
Object

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

data-webos-voice-focused
Boolean

Activates the component for voice control.

data-webos-voice-group-label
String

The voice control group label.

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'
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}
        ...
    />
)
spacing
Number

The spacing between items.

Default: 0
verticalScrollbar
String

Specifies how to show vertical scrollbar.

Valid values are:

  • 'auto',

  • 'visible', and

  • 'hidden'.

Default: 'auto'

VirtualListBasicComponent

A basic base component for VirtualList and VirtualGridList.

import {VirtualListBasic} from '@enact/ui/VirtualList';
Properties
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.

data-webos-voice-disabled
Boolean

Disable voice control feature of component.

data-webos-voice-focused
Boolean

Activates the component for voice control.

data-webos-voice-group-label
String

The voice control group label.

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

gridListItemSizeShapeObject

The shape for the grid list item size in a list for VirtualGridList.

minWidth •
Number

The minimum width of the grid list item.

minHeight •
Number

The minimum height of the grid list item.

itemSizesShapeObject

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

minSize •
Number

The minimum size of the list item.

size •
ArrayNumber

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

ArrayBooleanFunctionModuleNumberObjectString