VirtualList

Type: React component

How to get VirtualList?

JavaScript

import { VirtualList } from 'fds/components';

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

  1. animate

    (Optional)

    Type: 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

  2. estimatedItemHeight

    (Required)

    Type: 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

    (Optional)

    Type: Boolean

    Whether or not keyboard behavior in the component is enabled.

    Default value

  4. idToScrollIntoView

    (Optional)

    Type: 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

  5. isItemChanged

    (Optional)

    Type: 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

    Returns

    Default value

  6. itemKeyToUseAsId

    (Optional)

    Type: 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

  7. items

    (Required)

    Type: Array

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

  8. itemsMinWidth

    (Optional)

    Type: 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

  9. maxHeight

    (Optional)

    Type: Number | String

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

    Default value

  10. onAfterInitialRender

    (Optional)

    Type: Function

    Default value

  11. onItemClick

    (Optional)

    Type: Function

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

    Arguments

    Default value

  12. onItemDoubleClick

    (Optional)

    Type: Function

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

    Arguments

    Default value

  13. onRef

    (Optional)

    Type: Function

    Default value

  14. onResize

    (Optional)

    Type: Function

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

    Default value

  15. paddingSize

    (Optional)

    Type: 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

  16. renderItem

    (Required)

    Type: Function

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

    Arguments

    Returns

  17. scrollIntoViewDirection

    (Optional)

    Type: 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

  18. selectedItems

    (Required)

    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.

    Default value

  19. spaceVerticalSize

    (Optional)

    Type: 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

  20. virtualBufferFactor

    (Optional)

    Type: 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