Compared to the DataTable this package is low-level, affording you the control necessary to impact the performance of very large tables.

Usage

The main parts:

VBody is a very thin wrapper around react-window's FixedSizeList.
VTable must wrap the other table elements; it's used to prepare internal context. Among some other things, this implements a resize observer to support fluid width tables.

The other V* primitives are simple DOM elements with some accessibility attributes and minor styles to support users with assistive technologies and help maintain the Balance aesthetic.

Basic

The primary purpose of this package is to virtually render table rows using TBody. Required props are:

height: number Height of the list.
itemCount: number Total number of items in the list.
itemSize: number Height of each row in the table.

Ensure you pass style to the outer-most element of the item renderer (this is used for positioning).

Edit in Playroom

const { sizing } = useTheme();
const columns = [null, { width: 100, align: 'end' }];
return (
  <VTable columns={columns}>
    <VBody height={150} itemCount={500} itemSize={sizing.small}>
      {({ index, style }) => (
        <VRow striped={index % 2 === 0} style={style}>
          <VCell>
            <Text size="small">Row</Text>
          </VCell>
          <VCell>
            <Text size="small">{index}</Text>
          </VCell>
        </VRow>
      )}
    </VBody>
  </VTable>
);

Memoization

We recommend using React.memo() to memoize the component that will render each row. This package exposes a helper utility propsAreEqual to pass as the second argument for prop comparison.

Edit in Playroom

const { sizing } = useTheme();
const columns = [null, { width: 100, align: 'end' }];
const ItemRenderer = React.memo(
  ({ index, style }) => (
    <VRow striped={index % 2 === 0} style={style}>
      <VCell>
        <Text size="small">Row</Text>
      </VCell>
      <VCell>
        <Text size="small">{index}</Text>
      </VCell>
    </VRow>
  ),
  propsAreEqual
);
return (
  <VTable columns={columns}>
    <VBody height={150} itemCount={500} itemSize={sizing.small}>
      {ItemRenderer}
    </VBody>
  </VTable>
);

Accessing data

When creating the item renderer outside of the component it will be rendered in, you need a way to access the table data. Passing itemData to the VBody will make data available as a property to the item renderer.

Edit in Playroom

const { sizing } = useTheme();
const columns = [null, { width: 240 }];
const itemData = [
  { name: "Malena O' Donohue", email: 'mo0@fastcompany.com' },
  { name: 'Annabella Dye', email: 'adye1@blogspot.com' },
  { name: 'Say Torfin', email: 'tsay@indiegogo.com' },
  { name: 'Roddy Ashfull', email: 'rashfull3@time.com' },
  { name: 'Jarid Cardinal', email: 'cardinal.j@spiegel.de' },
  { name: 'Pembroke Knath', email: 'pknath5@ed.gov' },
  { name: 'Tricia Bouldon', email: 'tbouldon6@google.com.au' },
  { name: 'Jsandye Maclaine', email: 'maclaine.j@opensource.org' },
  { name: 'Norina Chatteris', email: 'nchatteris8@dmoz.org' },
  { name: 'Loree Keogh', email: 'lkeogh9@jugem.jp' },
];
const ItemRenderer = React.memo(({ data, index, style }) => {
  const item = data[index];
  return (
    <VRow striped={index % 2 === 0} style={style}>
      <VCell>
        <Text size="small">{item.name}</Text>
      </VCell>
      <VCell>
        <Text size="small">{item.email}</Text>
      </VCell>
    </VRow>
  );
}, propsAreEqual);
return (
  <VTable columns={columns}>
    <VBody
      height={150}
      itemCount={itemData.length}
      itemSize={sizing.small}
      itemData={itemData}
    >
      {ItemRenderer}
    </VBody>
  </VTable>
);

Primitives

Examples of using the various table primitives available.

Edit in Playroom

const { sizing } = useTheme();
const columns = [null, { width: 100, align: 'end' }];
const itemHeight = sizing.small;
const itemCount = 500;
const ItemRenderer = React.memo(
  ({ index, style }) => (
    <VRow striped={index % 2 === 0} style={style}>
      <VCell>
        <Text size="small">Row</Text>
      </VCell>
      <VCell>
        <Text size="small">{index}</Text>
      </VCell>
    </VRow>
  ),
  propsAreEqual
);
const tableHeader = (
  <VHead>
    <VRow style={{ height: itemHeight }}>
      <VCell>
        <Text size="small" color="muted">
          Title
        </Text>
      </VCell>
      <VCell>
        <Text size="small" color="muted">
          Index
        </Text>
      </VCell>
    </VRow>
  </VHead>
);
const tableFooter = (
  <VFoot>
    <VRow style={{ height: itemHeight }}>
      <VCell>
        <Text size="small" color="muted">
          Total
        </Text>
      </VCell>
      <VCell>
        <Text size="small" color="muted">
          {Array(itemCount)
            .fill()
            .reduce((a, _, i) => a + i, 0)}
        </Text>
      </VCell>
    </VRow>
  </VFoot>
);
return (
  <VTable columns={columns}>
    {tableHeader}
    <VBody height={150} itemCount={itemCount} itemSize={itemHeight}>
      {ItemRenderer}
    </VBody>
    {tableFooter}
  </VTable>
);

Row

To aid consumers with styling the rows of the VirtualDataTable there are 2 optional props available for the table row:

striped is used to get the "zebra pattern" muted background colour on the row.
tone is used to highlight a row that contains issues. It takes two property values;
- tone="cautious", use for a row that need attention.
- tone="critical", use for a row that contain errors.

Edit in Playroom

const columns = [null, { width: 240 }, { width: 120, align: 'end' }];
const { sizing } = useTheme();
const itemHeight = sizing.small;
const rawData = [
  { name: "Malena O' Donohue", email: 'mo0@fastcompany.com', age: 36 },
  { name: 'Annabella Dye', email: 'adye1@blogspot.com', age: 49 },
  { name: 'Say Torfin', email: 'tsay@indiegogo.com', age: 74 },
  { name: 'Roddy Ashfull', email: 'rashfull3@time.com', age: 31 },
  { name: 'Jarid Cardinal', email: 'cardinal.j@spiegel.de', age: 54 },
  { name: 'Pembroke Knath', email: 'pknath5@ed.gov', age: 80 },
  { name: 'Tricia Bouldon', email: 'tbouldon6@google.com.au', age: 32 },
  { name: 'Jsandye Maclaine', email: 'maclaine.j@opensource.org', age: 22 },
  { name: 'Norina Chatteris', email: 'nchatteris8@dmoz.org', age: 62 },
  { name: 'Loree Keogh', email: 'lkeogh9@jugem.jp', age: 41 },
];
const ItemRenderer = React.memo(({ data, index, style }) => {
  const item = data[index];
  const tone = (() => {
    if (item.name === 'Annabella Dye' || item.name === "Malena O' Donohue") {
      return 'cautious';
    } else if (
      item.name === 'Roddy Ashfull' ||
      item.name === 'Jarid Cardinal'
    ) {
      return 'critical';
    } else {
      return '';
    }
  })();
  return (
    <VRow striped={index % 2 === 0} tone={tone} style={style}>
      <VCell>
        <Text size="xsmall">{item.name}</Text>
      </VCell>
      <VCell>
        <Text size="xsmall">{item.email}</Text>
      </VCell>
      <VCell>
        <Text size="xsmall">{item.age}</Text>
      </VCell>
    </VRow>
  );
}, propsAreEqual);
const tableHeader = (
  <VHead>
    <VRow style={{ height: itemHeight }}>
      <VCell>
        <Text size="xsmall" color="muted">
          Name
        </Text>
      </VCell>
      <VCell>
        <Text size="xsmall" color="muted">
          Email
        </Text>
      </VCell>
      <VCell>
        <Text size="xsmall" color="muted">
          Age
        </Text>
      </VCell>
    </VRow>
  </VHead>
);
return (
  <VTable columns={columns}>
    {tableHeader}
    <VBody
      height={150}
      itemCount={rawData.length}
      itemData={rawData}
      itemSize={itemHeight}
    >
      {ItemRenderer}
    </VBody>
  </VTable>
);

Sorting

To aid consumers with sorting data we expose a few helpers:

sortData A utility for sorting against object keys
SortButton A styled button to include in head cells
SortIndicator A component that surfaces the arrow SVGs

Edit in Playroom

const [sort, setSort] = React.useState({ key: 'name', asc: true });
const columns = [null, { width: 240 }, { width: 120, align: 'end' }];
const { sizing } = useTheme();
const itemHeight = sizing.small;
const rawData = [
  { name: "Malena O' Donohue", email: 'mo0@fastcompany.com', age: 36 },
  { name: 'Annabella Dye', email: 'adye1@blogspot.com', age: 49 },
  { name: 'Say Torfin', email: 'tsay@indiegogo.com', age: 74 },
  { name: 'Roddy Ashfull', email: 'rashfull3@time.com', age: 31 },
  { name: 'Jarid Cardinal', email: 'cardinal.j@spiegel.de', age: 54 },
  { name: 'Pembroke Knath', email: 'pknath5@ed.gov', age: 80 },
  { name: 'Tricia Bouldon', email: 'tbouldon6@google.com.au', age: 32 },
  { name: 'Jsandye Maclaine', email: 'maclaine.j@opensource.org', age: 22 },
  { name: 'Norina Chatteris', email: 'nchatteris8@dmoz.org', age: 62 },
  { name: 'Loree Keogh', email: 'lkeogh9@jugem.jp', age: 41 },
];
const ItemRenderer = React.memo(({ data, index, style }) => {
  const item = data[index];
  return (
    <VRow striped={index % 2 === 0} style={style}>
      <VCell>
        <Text size="small">{item.name}</Text>
      </VCell>
      <VCell>
        <Text size="small">{item.email}</Text>
      </VCell>
      <VCell>
        <Text size="small">{item.age}</Text>
      </VCell>
    </VRow>
  );
}, propsAreEqual);
const handleSort = React.useCallback(
  (key) => () => {
    setSort((v) => ({
      key: key,
      asc: v.key === key ? !v.asc : true,
    }));
  },
  [setSort]
);
const tableHeader = (
  <VHead>
    <VRow style={{ height: itemHeight }}>
      <VCell>
        <SortButton
          active={sort.key === 'name'}
          asc={sort.asc}
          onClick={handleSort('name')}
        >
          Name
        </SortButton>
      </VCell>
      <VCell>
        <SortButton
          active={sort.key === 'email'}
          asc={sort.asc}
          onClick={handleSort('email')}
        >
          Email
        </SortButton>
      </VCell>
      <VCell>
        <SortButton
          active={sort.key === 'age'}
          asc={sort.asc}
          onClick={handleSort('age')}
        >
          Age
        </SortButton>
      </VCell>
    </VRow>
  </VHead>
);
const itemData = React.useMemo(() => sortData(rawData, sort), [rawData, sort]);
return (
  <VTable columns={columns}>
    {tableHeader}
    <VBody
      height={150}
      itemCount={itemData.length}
      itemData={itemData}
      itemSize={itemHeight}
    >
      {ItemRenderer}
    </VBody>
  </VTable>
);

Virtualized Data Table

Usage

Basic

Memoization

Accessing data

Primitives

Header / Footer

Row

Sorting