VirtualGrid

How to get VirtualGrid

import { VirtualGrid } from 'fds/components';

Type: Component

A VirtualList, specifically made for rendering rows of GridItem components. Only renders the rows that are visible within the "viewport" of the grid. This behavior drastically increases the performance of a grid 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, VirtualGrid supports scrolling items into view. By changing the "idToScrollIntoView" prop, VirtualGrid will scroll the item with that id into view.

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

Props

# Name Type Description
1. estimatedRowHeight Number

An estimation of the average height of a row of GridItem components returned from "renderItem". VirtualGrid will use this to determine the height of the vertical scrollbar. When a row is measured, VirtualGrid will use the measured height instead of the estimated height.

2. [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
3. [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"
4. items Array<ItemWithId>
  ItemWithId

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

Properties

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.

5. [itemSize] String

The size in which the GridItem components should render. The possible values are:

  • 'xs'

  • 's'

  • 'm'

  • 'l'

  Default value
"m"
6. [maxHeight] Number | String

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

  Default value
null
7. [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.

8. [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.

9. [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
10. 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
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.

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.

size String

The size in which the GridItem components should render. The possible values are:

  • 'xs'

  • 's'

  • 'm'

  • 'l'

  Returns

Type: ReactElement

11. [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"
12. 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.

13. [spaceSize] Number | String

The amount of space (or margin) between the children of the component. Depending on the flexDirection value, either horizontal or vertical space is created.

This should be one of the following values:

  • 0 (zero, no margin at all)

  • 's' (small)

  • 'm' (medium)

  • 'l' (large)

  Default value
0
14. [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
15. onResize
Was this page helpful?