React ViewPort List

Methods

scrollToIndex

scrollToIndex method has only one param - options;

Options param

| name | type | default | description | | ------------ | ------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | index | number | -1 | Item index for scroll. | | alignToTop | boolean | true | scrollIntoView param. Only boolean option supported. | | offset | number | 0 | Offset after scrollIntoView call.
This value will be added to the scroll after scroll to index. | | delay | number | -1 | setTimeout delay for initial scrollToIndex. | | prerender | number | 0 | This value will modify initial start index and initial end index like [index - initialPrerender, index + initialPrerender].
You can use it to avoid blank screen with only one initial item rendered |

Usage

import { useRef } from 'react';
import { ViewportList } from 'react-viewport-list';

const ItemList = ({
  items,
}: {
  items: { id: string; title: string }[];
}) => {
  const ref = useRef(null);
  const listRef = useRef(null);

  return (
    <div className="scroll-container" ref={ref}>
      <ViewportList
        ref={listRef}
        viewportRef={ref}
        items={items}
      >
        {(item) => (
          <div key={item.id} className="item">
            {item.title}
          </div>
        )}
      </ViewportList>
      <button
        className="up-button"
        onClick={() =>
          listRef.current.scrollToIndex({
            index: 0,
          })
        }
      />
    </div>
  );
};

export { ItemList };

getScrollPosition

getScrollPosition returns an object with scroll position: { index: number, offset: number }

Returns

| name | type | description | | -------- | ------ | ----------------------------------------------------------------------------------------------------- | | index | number | Item index for scroll. | | offset | number | Offset after scrollIntoView call.
This value will be added to the scroll after scroll to index. |

If items=[] or count=0 getScrollPosition returns { index: -1; offset: 0 }

Usage

import { useEffect, useRef } from 'react';
import { ViewportList } from 'react-viewport-list';

const ItemList = ({
  items,
}: {
  items: { id: string; title: string }[];
}) => {
  const ref = useRef(null);
  const listRef = useRef(null);

  useEffect(
    () => () => {
      window.sessionStorage.setItem(
        'lastScrollPosition',
        JSON.stringify(
          listRef.current.getScrollPosition(),
        ),
      );
    },
    [],
  );

  return (
    <div className="scroll-container" ref={ref}>
      <ViewportList
        ref={listRef}
        viewportRef={ref}
        items={items}
      >
        {(item) => (
          <div key={item.id} className="item">
            {item.title}
          </div>
        )}
      </ViewportList>
      <button className="up-button" />
    </div>
  );
};

export { ItemList };

Performance

If you have performance issues, you can add will-change: transform to a scroll container.

You should remember that in some situations will-change: transform can cause performance issues instead of fixing them.

.scroll-container {
  will-change: transform;
}

Children pseudo-classes

ViewportList render two elements (spacers) before first rendered item and after last rendered item. That's why children pseudo-classes like :nth-child(), :last-child, :first-child may work incorrectly.

Margin

If you want more accurate virtualizing you should use equal margin for all items. Also, you should use margin-top or margin-bottom (not both) for axis="y" and margin-right or margin-left (not both) for axis="x".

If you want to use different margins and stil want more accurate virtualizing you can wrap your items in some element like <div> and use padding instead of margin.

Non-keyed

You should avoid non-keyed usage of list. You should provide unique key prop for each list items. If you have issues with scroll in Safari and other browsers without overflow-anchor support, check item's key prop.

Advanced Usage

• Grouping

  ViewportList render Fragment with items in viewport. So, grouping just work.

  import { useRef } from 'react';
  import { ViewportList } from 'react-viewport-list';
  
  const GroupedItemList = ({
    keyItems,
    items,
  }: {
    keyItems: { id: string; title: string }[];
    items: { id: string; title: string }[];
  }) => {
    const ref = useRef(null);
  
    return (
      <div className="scroll-container" ref={ref}>
        <span className="group-title">
          Key Items
        </span>
        <ViewportList
          viewportRef={ref}
          items={keyItems}
        >
          {(item) => (
            <div
              key={item.id}
              className="key-item"
            >
              {item.title}
            </div>
          )}
        </ViewportList>
        <span className="group-title">Items</span>
        <ViewportList
          viewportRef={ref}
          items={items}
        >
          {(item) => (
            <div key={item.id} className="item">
              {item.title}
            </div>
          )}
        </ViewportList>
      </div>
    );
  };
  export { GroupedItemList };
  

• Sorting

  You can use React Sortable HOC

  import { useRef } from 'react';
  import {
    SortableContainer,
    SortableElement,
  } from 'react-sortable-hoc';
  import { ViewportList } from 'react-viewport-list';
  
  const SortableList = SortableContainer(
    ({ innerRef, ...rest }) => (
      <div {...rest} ref={innerRef} />
    ),
  );
  
  const SortableItem = SortableElement(
    (props) => <div {...props} />,
  );
  
  const SortableItemList = ({
    items,
    onSortEnd,
  }) => {
    const ref = useRef(null);
  
    return (
      <SortableList
        innerRef={ref}
        className="scroll-container"
        onSortEnd={onSortEnd}
      >
        <ViewportList
          viewportRef={ref}
          items={items}
        >
          {(item, index) => (
            <SortableItem
              key={index}
              index={index}
              className="item"
            >
              {item.title}
            </SortableItem>
          )}
        </ViewportList>
      </SortableList>
    );
  };
  
  export { SortableItemList };
  

• Scroll to position

  Scroll to position may work incorrectly because scrollHeight and scrollTop (or scrollWidth and scrollLeft) changed automatically while scrolling. But you can scroll to position with scrollToIndex method with { index: 0, offset: scrollPosition }. For initial scroll to position you can use initialIndex={0} and initialOffset={scrollPosition}. You should remember that after scroll happened scroll position can be not equal to specified offset.

  import { useRef } from 'react';
  import { ViewportList } from 'react-viewport-list';
  
  const ItemList = ({
    items,
    savedScroll,
  }: {
    items: { id: string; title: string }[];
    savedScroll: number;
  }) => {
    const ref = useRef(null);
    const listRef = useRef(null);
  
    return (
      <div className="scroll-container" ref={ref}>
        <ViewportList
          ref={listRef}
          viewportRef={ref}
          items={items}
          initialIndex={0}
          initialOffset={savedScroll}
        >
          {(item) => (
            <div key={item.id} className="item">
              {item.title}
            </div>
          )}
        </ViewportList>
        <button
          className="up-button"
          onClick={() => {
            // this sets scrollTop of "scroll-container" to 1000
            listRef.current.scrollToIndex({
              index: 0,
              offset: 1000,
            });
          }}
        />
      </div>
    );
  };
  
  export { ItemList };
  

• Tests

  You can mock ViewportList for unit tests:

  import {
    useImperativeHandle,
    forwardRef,
  } from 'react';
  
  export const ViewportListMock = forwardRef(
    ({ items = [], children }, ref) => {
      useImperativeHandle(
        ref,
        () => ({
          scrollToIndex: () => {},
        }),
        [],
      );
  
      return (
        <>
          <div />
          {items.map(children)}
          <div />
        </>
      );
    },
  );
  
  export default ViewportListMock;