Table

Import#

import { Table } from '@volue/wave-react';

Table is a compound component that consists of multiple parts which can be composed together to achieve the desired table interface:

• ​
  Table: The wrapper that contains all the parts of a table.
• ​
  Table.Head: The container that defines the head of the table's columns (equivalent of <thead> HTML element).
• ​
  Table.Header: A convenience container wrapping content into Table.Head with single Table.Row inside.
• ​
  Table.ColumnHeader: Renders the header cell of a column (equivalent of native <th> element). Wraps text content into Table.TableColumnHeaderContent and optionally shows Table.SortIndicator.
• ​
  Table.ColumnHeaderContent: Wrapper for column's header text contents.
• ​
  Table.Body: The container grouping a set of Table.Rows that are main content of the table (equivalent of native <tbody> element).
• ​
  Table.Row: Renders table row (equivalent of native <tr> element).
• ​
  Table.Cell: Cell to be placed in the Table.Row that displays single piece of data in the column (equivalent of native <td> element). Wraps text content into Table.CellContent automatically.
• ​
  Table.CellContent: Wrapper for cell's text contents.
• ​
  Table.SelectionCell: Composes Table.Cell and Table.SelectionCellCheckbox, to render a cell with checkbox for implementing selection of rows.
• ​
  Table.SelectionCellCheckbox: Customized Checkbox component to be placed in the table cell.
• ​
  Table.Foot: The container grouping a set of Table.Rows which is placed at the bottom of the table (equivalent of native <tfoot> element).
• ​
  Table.Footer: A convenience container wrapping content into Table.Foot with single Table.Row inside.
• ​
  Table.EmptyState: The wrapper for providing additional context when the table data is either unavailable or nonexistent.

Examples#

Basic#

Table appearance#

The root Table component accepts following properties to infuence the appearance of every cell:

• ​
  cellSize — controls the size of each cell.
• ​
  alignY — controls vertical alignment of content inside cells.
• ​
  overflowStrategy — wraps or truncate content inside a cell.
• ​
  highlightOnHover — controls whether rows within Table.Body should be highlighted on hover.
• ​
  rowSeparation - controls the appearance of row separation.

Outer outline of the Table can be disabled by setting outlined property to false:

Cell appearance#

The Table.Cell component accepts following props to adjust appearance:

• ​
  align — controls the horizontal alignment of cell contents.
• ​
  maxWidth — sets the maximum width of the cell.
• ​
  minWidth — sets the minimum width of the cell.
• ​
  width — sets the width of the cell.

Rows selection#

Use Table.SelectionCell to implement selection of rows.

Table overflow#

When there isn’t enough space to fit all the rows or columns within table's container, it becomes scrollable.

You can apply sticky positioning to Table.Header and Table.Footer along the vertical axis via the stickyOffset property:

• ​
  the header will be offset against the top edge.
• ​
  the footer will be offset against the bottom edge.

Table.ColumnHeader and Table.Cell can be "sticky" along the horizontal axis:

• ​
  positive values (e.g. 0) will offset the cell against the left edge.
• ​
  negative values (e.g. -0) will offset the cell against the right edge.

Synced scroll#

By default, stickyOffset is relative to nearest scrolling ancestor (the Table itself). If the table doesn't scroll vertically within the overflowing container and you want the Table.Header or Table.Footer to stick while scrolling on the document window, use syncScroll property.

Custom cell content#

You may provide any custom content to Table.ColumnHeader and Table.Cell.

Each individual table cell can support multiple rows of text. This is useful when you want to provide related details in a table without adding additional columns, such as placing an employee's email address beneath their name.

Row actions#

Row actions can be represented as icon buttons. When there is only one action available, you may provide a tooltip for better clarity.

When multiple actions are available on the row, use Menu component for displaying list of actions.

In some cases, you may want to attach an action to an entire row.

Highlighting rows#

You can highlight individual rows with isHighlighted property. Highlights provide additional visual prominence to a row and is useful to quickly differentiate it from other rows.

Row tones#

Table.Row supports setting tone property.

Tones are typicaly used to emphasize the status of a row and faciliate users in identyfing which parts of the table require attention.

Supported tones include:

• ​
  danger - for statuses that imply error, failure or problem.
• ​
  success - for statuses that are positive, e.g. confirmations.
• ​
  warning - for statuses that are in-progress, pending, or that could require user intervention.

Note that you can provide a custom tone by using tone="custom" property and assigning specific color to --table-cell-bg-color CSS variable.

Cell tones#

Similar to row tones, a single cell also supports setting tone property. This can be useful to grab a user’s attention on a specific cell(s) in the table.

Loading state#

Rather than using a Spinner component, you can use the Skeleton placeholders in the cells to create a more pleasant loading experience.

Empty state#

When there is no data to feed the table or no match can be found while filtering, render Table.EmptyState instead of Table.Body to provide additional context for the user.

For example, if a table of users isn’t populated yet, the empty state within the table shows the user what data to expect and optionally offers an action to populate the table.

Table inside a card#

The table can be contextually styled to better fit the container it is placed into, such as Card.

Overflowing cell content#

You may use useHasOverflow hook to dynamically apply Tooltip only when content overflows Table.CellContent area. The tooltip will show full content when hovered over the abbreviated cell text.

import { useHasOverflow } from '@volue/wave-react';

const TableCellContentWithTooltip = React.memo(({ children }) => {
  const [cellContentRef, hasHorizontalOverflow] = useHasOverflow({
    observeMutations: true
  });

  return hasHorizontalOverflow ? (
    <Tooltip content={children} css={{ maxWidth: 320 }}>
      <Table.CellContent ref={cellContentRef}>{children}</Table.CellContent>
    </Tooltip>
  ) : (
    <Table.CellContent ref={cellContentRef}>{children}</Table.CellContent>
  );
});

Drag and drop#

With libraries such as react-dnd you can easily implement drag-and-drop feature over table rows and change their order.

import { DndProvider } from 'react-dnd';
import { HTML5Backend } from 'react-dnd-html5-backend';

function App() {
  return (
    <DndProvider backend={HTML5Backend}>
      <Main />
    </DndProvider>
  );
}

react-dnd provides a way to separate dragRef and dropRef to use them on different DOM elements. It can be useful when there are multiple actionable elements in table rows.

import { useDrag, useDrop } from 'react-dnd';
import { useForkRef } from '@volue/wave-react';

const DraggableRowWithHandle = React.forwardRef(
  ({ row, reorderRow, children, ...delegated }, forwardedRef) => {
    const [{ isOver }, dropRef] = useDrop({
      accept: 'row',
      drop: draggedRow => reorderRow(draggedRow.id, row.id),
      collect: monitor => ({
        isOver: monitor.isOver()
      })
    });

    const [{ isDragging }, dragRef, previewRef] = useDrag({
      item: { id: row.id },
      type: 'row',
      collect: monitor => ({
        isDragging: monitor.isDragging()
      })
    });

    const composedRef = useForkRef(forwardedRef, dropRef, previewRef);

    const tableRowStatus = isDragging
      ? 'dragging'
      : isOver
        ? 'dropTarget'
        : undefined;

    return (
      <Table.Row ref={composedRef} {...delegated} status={tableRowStatus}>
        <Table.Cell width={48} ref={dragRef} css={{ cursor: 'grab' }}>
          <SvgIcon iconName="dragAndDrop" />
        </Table.Cell>
        {children}
      </Table.Row>
    );
  }
);

dragRef and dropRef can be merged into one ref which can be useful to make whole rows draggable.

import { useDrag, useDrop } from 'react-dnd';
import { useForkRef } from '@volue/wave-react';

const DraggableRow = React.forwardRef(
  ({ row, reorderRow, children, ...delegated }, forwardedRef) => {
    const [{ isOver }, dropRef] = useDrop({
      accept: 'row',
      drop: draggedRow => reorderRow(draggedRow.id, row.id),
      collect: monitor => ({
        isOver: monitor.isOver()
      })
    });

    const [{ isDragging }, dragRef] = useDrag({
      item: { id: row.id },
      type: 'row',
      collect: monitor => ({
        isDragging: monitor.isDragging()
      })
    });

    const composedRef = useForkRef(forwardedRef, dragRef, dropRef);

    const tableRowStatus = isDragging
      ? 'dragging'
      : isOver
        ? 'dropTarget'
        : undefined;

    return (
      <Table.Row
        ref={composedRef}
        css={{ cursor: 'move', ...css }}
        {...delegated}
        status={tableRowStatus}
      />
    );
  }
);

Integration with TanStack Table#

Table component consists of lightweight, "primitive" buliding blocks designed for composability. Primitives are low-level components that assume as little as possible about their usage and they don't own any complex state.

This works well for simple or static tables, but there are instances where functionality such as sorting, search, filtering, virtualization​ or pagination are required. This kind of functionality is out of scope for the Table component, as the spectrum of possible use-cases is too broad for a single component to cover effectively. We aim to avoid monolithic components with a lot of assumptions about how you use them and increased API surface area, i.e. endless prop configuration.

Whilst the Table component is limited out of the box, these same limitations make it very easy to integrate with third-party libraries which offer advanced functionality. One such library that we recommend is TanStack Table​. It is a headless UI library​, which supplies you with functions, state and utilities to add more advanced functionality and interactions to your tables. It does not bring any user interface or styles itself, making it a perfect extension for Wave's Table.

Examples below show how to combine TanStack Table​ with Wave's Table.

npm install @tanstack/react-table --save
# or
yarn add @tanstack/react-table

Basic#

import {
  flexRender,
  getCoreRowModel,
  useReactTable,
  createColumnHelper
} from '@tanstack/react-table';

Sorting columns#

Use TanStack Table Sorting API​ together with onClick and sort properties on Table.ColumnHeader to render the UI for a sort indicator and allow the user to change the sort order of the data.

import {
  flexRender,
  getCoreRowModel,
  getSortedRowModel,
  useReactTable,
  createColumnHelper
} from '@tanstack/react-table';

Filtering#

Filtering data can be implemented with TanStack Table Filters API​. Table data can be filtered globally with use of globalFilter prop or it can be column filtered with columnFilters.

import {
  flexRender,
  getCoreRowModel,
  getFilteredRowModel,
  useReactTable,
  createColumnHelper
} from '@tanstack/react-table';

Selecting rows#

Rows selection can be implemented with Row Selection API​. In the example below batch actions will be shown upon rows selection.

import {
  flexRender,
  getCoreRowModel,
  useReactTable,
  createColumnHelper
} from '@tanstack/react-table';

Pagination#

With help of Pagination component to display the pagination UI and TanStack Pagination API​, larger table data sets can be split into pages.

import {
  flexRender,
  getCoreRowModel,
  getPaginationRowModel,
  useReactTable,
  createColumnHelper
} from '@tanstack/react-table';

Columns visibility#

Toggling columns visibility can be implemented with Visiblity API​.

import {
  flexRender,
  getCoreRowModel,
  useReactTable,
  createColumnHelper
} from '@tanstack/react-table';

Rows virtualization#

Rendering large amounts of rows can be inefficient. With virtualization​ (or windowing) of data, only currently visible rows are rendered to DOM to deliver best performance and user experience.

import {
  flexRender,
  getCoreRowModel,
  useReactTable,
  createColumnHelper
} from '@tanstack/react-table';
import { useVirtualizer } from '@tanstack/react-virtual';

API Reference#

Table#

Table.Head#

Table.Header#

Table.ColumnHeader#

Table.ColumnHeaderContent#

Table.SortIndicator#

Table.Body#

Table.Row#

Table.Cell#

Table.CellContent#

Table.SelectionCell#

Table.SelectionCellCheckbox#

Table.Foot#

Table.Footer#

Table.EmptyState#