VirtualList

How to get VirtualList

import { VirtualList } from 'fds/components';

Type: Component

A virtualized list of arbitrary items (set using the renderItem prop), which only renders the items that are visible within the "viewport" of the list. This behavior drastically increases the performance of a list with a lot of items (with high render costs). Optionally a "virtualBufferFactor" prop can be set to increase the amount of items being rendered off-screen.

Additionally, VirtualList supports scrolling items into view. By changing the "idToScrollIntoView" prop, VirtualList will scroll the item with that id into view.

Make sure to implement the onRef callback and call the measureItem callback when needed to allow VirtualList to accurately scroll to items. Both are provided as parameters to renderItem. See the renderItem API docs below for more info.

VirtualList renders a container that is stretched to the maximum available height using flexbox. Make sure the parent of VirtualList is a Flex component or is using the flex styling mixin.

Props

# Name Type Description
1. [animate] Boolean

Whether or not the items have a mount/unmount animation. When set to true and changing the "items" prop, it will merge in the next set of items and set additional properties on each item at specified times:

  • item.isAdded: set when the item has been added.

  • item.isRemoved: set when the item has been removed.

  • item.isMoved: set when the position of the item in the array has been moved.

Additionally an "onItemIsRemoved" callback property is passed to the "renderItem" prop. This callback should be called when the unmount animation is done. This will result in the item being completely removed from the set of items in the state and eventually the DOM.


  Default value
false
2. estimatedItemHeight Number

An estimation of the average height of the elements/components returned from "renderItem". VirtualList will use this to determine the height of the vertical scrollbar and to more accurately scroll items into view. When an item is measured, VirtualList will use the measured height instead of the estimated height. To ensure your items are measured by VirtualList, use the onRef callback provided by "renderItem". If your items change height dynamically, make sure to call the measureItem callback provided by "renderItem". See the "renderItem" docs below for more info.

3. [hasKeyboardBehavior] Boolean

Whether or not keyboard behavior in the component is enabled.

  Default value
false
4. [idToScrollIntoView] Number | String

The id of the item to scroll into the currently visible view of the list. If the specified item is already within the view, no scrolling will occur. Note that if a custom "itemKeyToUseAsId" prop is set, this will be used as the key to find the item based on this prop.

  Default value
null
5. [isItemChanged] Function

Callback function used to specify whether an item has been changed. Is called from several points in VirtualList to determine when to update the state.

Defaults to a referential compare of the new and old item.


  Arguments
# Name Type Description
1. newItem Object

The item from the current render.

An item with an identifier property, used to distinguish items from each other.

In some cases, the key of the "id" property is configurable using a "itemKeyToUseAsId" prop.

  Members

Members

Name Type Description
id String | Number

The unique identifier of the item, used to distinguish items from each other, eg. when determining the selected item. The value of this identifier should always be unique within a set of items.

2. oldItem Object

The item from the previous render.

An item with an identifier property, used to distinguish items from each other.

In some cases, the key of the "id" property is configurable using a "itemKeyToUseAsId" prop.

  Members

Members

Name Type Description
id String | Number

The unique identifier of the item, used to distinguish items from each other, eg. when determining the selected item. The value of this identifier should always be unique within a set of items.

  Returns

Type: Boolean

Whether or not the item is changed.

6. [itemKeyToUseAsId] String

The property key from each item in the items array to use as the id. Since items are arbitrary and it can sometimes be devious to map them around, this serves as a way to choose which property key should be used as the unique id.

  Default value
"id"
7. items Array

An arbitrary set of items, each item should at least include the property set as "itemKeyToUseAsId".

8. [itemsMinWidth] Number

The minimum width of the items container. If this exceeds the width of the scroll container VirtualList introduces, a horizontal scrollbar will be shown.


  Default value
null
9. [maxHeight] Number | String

The maximum height of the component, sets the CSS "max-height" property.

  Default value
null
10. [onAfterInitialRender] Function
11. [onItemClick] Function

A callback that is called whenever a rendered item is clicked and is not in a disabled state.


  Arguments
# Name Type Description
1. item Object

The clicked item.

12. [onItemDoubleClick] Function

A callback that is called whenever a rendered item is double clicked and is not in a disabled state.


  Arguments
# Name Type Description
1. item Object

The double clicked item.

13. [onRef] Function
14. [onResize] Function

A callback that is called whenever a component's width and/or height changes.

15. [paddingSize] Number | String | Object

The amount of padding rendered by the component.

This should be a either, A single size value, one of the following values:

  • 0 (zero, no padding at all)

  • 's' (small)

  • 'm' (medium)

  • 'l' (large) to set the paddingSize for the top, right, bottom and left side to a single shared value.

Or you can pass an object whose properties determine a specific padding size for either:

  • 'horizontal': %single size value% to set the 'left' and 'right' padding to the given size value (one of the values listed above)

  • 'vertical': %single size value% to set the 'top' and 'bottom' padding

Or you can pass any combination of 'bottom', 'horizontal', 'left', 'right', 'top', 'vertical', where the more specific keys override the generic (eg. setting 'left': 's' and 'horizontal': 'm' would result in a padding size of 's' for the left side and a size of 'm' for the right side.

  Default value
0
16. renderItem Function

A callback that is called for each item in the items array which renders the item.


  Arguments
# Name Type Description
1. parameters Object
  Members

Members

Name Type Description
isHovered Boolean

Whether or not the component is currently hovered.

isSelected Boolean

Deprecated: with the removal of the "selectedItems" prop this should be managed in the component that implements VirtualList.

Whether or not the component should be rendered in a selected state.

item Object

An item with an identifier property, used to distinguish items from each other.

In some cases, the key of the "id" property is configurable using a "itemKeyToUseAsId" prop.

  Members

Members

Name Type Description
id String | Number

The unique identifier of the item, used to distinguish items from each other, eg. when determining the selected item. The value of this identifier should always be unique within a set of items.

key *

A identifier used by React to distinguish items rendered from an iterator function. Should be set as the "key" property on a component instance. This should preferably be a unique key (like an "id" coming from a backend/CMS). When items are being reordered, React uses this key property to determine which items should be rerendered.

measureItem Function

A callback that should be called whenever the item should be remeasured. The initial measurement is done automatically if you implement the onRef callback as described below. If whatever you render does not change it height, you don't have to call this callback.

onClick Function

A callback that is called whenever a rendered item is clicked and is not in a disabled state.


  Arguments
# Name Type Description
1. item Object

The clicked item.

onDoubleClick Function

A callback that is called whenever a rendered item is double clicked and is not in a disabled state.


  Arguments
# Name Type Description
1. item Object

The double clicked item.

onItemIsRemoved Function

A callback that should be called whenever the item is done animating and should be removed from the DOM. Should only be used when the "animate" prop is set to true.

onMouseEnter Function

A callback that is called whenever the pointer is moved over a rendered item. This callback is only fired when the pointer enters the rendered item.


  Arguments
# Name Type Description
1. item Object

The hovered item.

onMouseLeave Function

A callback that is called whenever the pointer is moved off a rendered item. This callback is only fired when the pointer leaves the rendered item.


  Arguments
# Name Type Description
1. item Object

The item that is hovered off.

onRef Function

Make sure to pass this callback prop through to whatever component you return in this function. Eg. if you return/render a Card, make sure you do: <Card onRef={onRef}>. This ensures the component is measured by VirtualList after it renders. This helps VirtualList in more accurately scrolling items into view and determining the size of the scroll bar. If whatever you render changes it height dynamically, make sure to call measureItem after the new height is applied.

  Returns

Type: ReactElement

17. [scrollIntoViewDirection] String

The direction in which to scroll the specified item into view. Correlates with the "scrollIdIntoView" prop.

  • This should be one of the following values:

  • 'auto' (minimally scrolls the specified item in view if the item is partially visible within the view, otherwise scrolls it into the top of the view)

  • 'bottom' (always scrolls the specified item into the bottom of the view)

  • 'top' (always scrolls the specified item into the top of the view)

  Default value
"auto"
18. selectedItems Array<SelectedItem>
  Default value
null

  SelectedItem

Type: Object

The item that is visually presented in a selected state. Expects an item in the same shape as expected by the "items" property.

19. [spaceVerticalSize] Number | String

The amount of vertical space (or margin) between the children of the component.

This should be one of the following values:

  • 0 (zero, no margin at all)

  • 's' (small)

  • 'm' (medium)

  • 'l' (large)

  Default value
0
20. [virtualBufferFactor] Number

The factor which a virtualized list (like VirtualList) uses to determine how much of the rendered items should be buffered off-screen. This helps increase the performance of the list by decreasing the amount of render hits that occur.

This factor is multiplied by the height of the list. For example, a list being 500 pixels high with a virtualBufferFactor of 2 would result in 1000 pixels worth of items being rendered off-screen on both the top and bottom of the list.

  Default value
2
Was this page helpful?