API

Props

keys

List of unique numbers or strings identifying and representing each cell.

keys: (string | number)[];

renderCell

Is called to render each cell.

type RenderCell = (
  key: string | number,
  style: ICellStyle,
  ref: React.Ref<any>,
  frame: IFrame,
  activeFrame: boolean
) => React.ReactNode | JSX.Element;

Arguments:

• key - the corresponding key from the keys prop
• style - ICellStyle should be passed to each cell to apply css transforms.
• ref - must be passed to the outer element. It is used to read the position of each cell (offsetLeft, offsetTop).
• frame - IFrame
• activeFrame - if it is the frame which is next to be rendered, see Terminology

renderWrapper

Is called to render the wrapper [optional]. Apply styling for how the cells should be positioned, e.g. flex or css grid

type RenderWrapper = (
  style: IWrapperStyle,
  ref: React.Ref<any>,
  cells: JSX.Element[],
  frame: IFrame,
  activeFrame: boolean
) => React.ReactNode | JSX.Element;

Arguments:

• style - IWrapperStyle should be passed to the element to update the height
• ref - must be passed to the outer element. It is used to read the height and width of the wrapper (offsetWidth, offsetHeight).
• cells - list of JSX elements to be rendered
• frame - IFrame
• activeFrame - if it is the frame which is next to be rendered, see Terminology

dynamicDirection

If the wrapper should grow/shrink vertically or horizontally when adding and removing cells.

If you don't add or remove cells you can set the dynamicDirection to 'off'. This will have some minor performance benefits as the COMMIT stage is skipped. During the COMMIT stage the wrapper is measured and transition-in styles are applied.

dynamicDirection: 'horizontal' | 'vertical' | 'off';

Example:

dynamicDirection = 'horizontal'

1

2

3

Moved horizontally

dynamicDirection = 'vertical'

1

2

3

Moved vertically

dynamicDirection = 'off' (better performance)

Variable size looks weird as new items

fly in and the height isn't animated

due to dynamicDirection = 'off'

Shuffle looks okay, since no

elements are removed or added

1

2

3

4

5

6

7

8

9

Moved vertically

Warning

You must set a fixed width / height on the wrapper if you have dynamicDirection="off" to prevent the wrapper from collapsing during the animation stage when every cell (child) is positioned absolute.

transitionDuration

Should match the longest css transition-duration used. If 0 transitions are disabled.

transitionDuration: number;

Advanced props

disableTransition [optional]

Disables all transition. Same as transitionDuration = 0

disableTransition?: boolean;

debugMeasure [optional]

Debug the measure stage.

Sets for how long in milliseconds the measure wrapper should be rendered.

By default the measure wrapper is hidden. When this prop is truthy it will be visible.

The measure wrapper should be the same width and height as the stale wrapper.

debugMeasure?: number;

Example:

debugMeasure = 1000

1

2

3

Moved horizontally

Interfaces

IFrame

/**
 * IFrame
 *
 * Holds information about the keys of rendered cells
 */
export interface IFrame {
  /**
   * The height of the container when all cells are rendered.
   */
  containerHeight: number | undefined;
  /**
   * The width of the container when all cells are rendered.
   */
  containerWidth: number | undefined;
  /**
   * The keys which should be rendered
   */
  keys: (string | number)[];
  /**
   * The positions of each cell
   */
  positions: IPositions;
  /**
   * A unique index used for debugging purposes to differentiate each IFrame
   */
  index: number;
  /**
   * If the frame has been measured
   */
  hasBeenMeasured: boolean;
  /**
   * a hash generated from the keys
   */
  hash: string;
}

ICellStyle

/**
 * ICellStyle
 *
 * The styles passed to a renderCell
 */
interface ICellStyle {
  position?: 'absolute';
  top?: string;
  left?: string;
  margin?: '0px';
  transition?: string;
  transform?: string;
}

IWrapperStyle

/**
 * IWrapperStyle
 *
 * The styles passed to the renderWrapper
 */
interface IWrapperStyle {
  // position absolute in MEASURE stage and position relative in ANIMATE and COMMIT stage
  // undefined in STALE stage
  position?: 'absolute' | 'relative';
  width?: number;
  height?: number;
  visibility?: 'hidden';
  zIndex?: -1;
}