Dynamic table

To add the DynamicTable component to your app:

1
2
import { DynamicTable } from "@forge/react";

Description

A dynamic table displays rows of data with built-in pagination, sorting, and re-ordering functionality.

Props

Types

Below are some helper types defined for the DynamicTable component. They should be inputted into DynamicTable as objects with the properties specified below each corresponding type.

RowType

The type of each row within a table.

RowCellType

The type of each cell within a row.

HeadCellType

The type of each cell within a header.

It contains all of RowCellType's properties, as well as the following:

I18nShape

Labels for the buttons used in pagination.

Examples

1
2
const createKey = (input) => {
  return input ? input.replace(/^(the|a|an)/, "").replace(/\s/g, "") : input;
}

// applied as rows in the form
export const rows = presidents.map((president, index) => ({
  key: `row-${index}-${president.name}`,
  cells: [
    {
      key: createKey(president.name),
      content: <Link href="">{president.name}</Link>,
    },
    {
      key: createKey(president.party),
      content: president.party,
    },
    {
      key: president.id,
      content: president.term,
    },
  ],
}));

export const head = {
  cells: [
    {
      key: "name",
      content: "Name",
      isSortable: true,
    },
    {
      key: "party",
      content: "Party",
      shouldTruncate: true,
      isSortable: true,
    },
    {
      key: "term",
      content: "Term",
      shouldTruncate: true,
      isSortable: true,
    },
  ],
};

Data used are as below:

1
2
export const presidents = [
  {
    id: 1,
    name: "George Washington",
    party: "None, Federalist",
    term: "1789-1797",
  },
  {
    id: 2,
    name: "John Adams",
    party: "Federalist",
    term: "1697-1701",
  },
  {
    id: 3,
    name: "Thomas Jefferson",
    party: "Democratic-Republican",
    term: "1801-1809",
  },
  {
    id: 4,
    name: "James Madison",
    party: "Democratic-Republican",
    term: "1809-1817",
  },
  {
    id: 5,
    name: "James Monroe",
    party: "Democratic-Republican",
    term: "1817-1825",
  },
  {
    id: 6,
    name: "John Quincy Adams",
    party: "Democratic-Republican",
    term: "1825-1829",
  },
  {
    id: 7,
    name: "Andrew Jackson",
    party: "Democrat",
    term: "1829-1837",
  },
  {
    id: 8,
    name: "Martin van Buren",
    party: "Democrat",
    term: "1837-1841",
  },
  {
    id: 9,
    name: "William H. Harrison",
    party: "Whig",
    term: "1841",
  },
  {
    id: 10,
    name: "John Tyler",
    party: "Whig",
    term: "1841-1845",
  },
  {
    id: 11,
    name: "James K. Polk",
    party: "Democrat",
    term: "1845-1849",
  },
];

Default

Dynamic table manages sorting, pagination, loading, and drag and drop state management by default.

1
2
import { DynamicTable } from "@forge/react";
import { head, rows } from "./data";

export default function Table() {
  return (
    <DynamicTable
      caption="List of US Presidents"
      head={head}
      rows={rows}
    />
  );
};

Sorting

Sorting a dynamic table is done based on the key set on each cell. You can sort the table via directly interacting with the table headers, or through the sortKey, sortOrder, defaultSortKey and defaultSortOrder properties.

1
2
import { DynamicTable } from "@forge/react";
import { head, rows } from "./data";

export default function TableSorted() {
  return (
    <DynamicTable
      rowsPerPage={5}
      head={head}
      rows={rows}
    />
  );
};

Loading states

Dynamic table uses a spinner to denote loading state. This is toggled by the isLoading prop.

Table content is set to 20% opacity in this loading state.

1
2
import { DynamicTable } from "@forge/react";
import { head, rows } from "./data";

export default function TableLoading() {
  return (
    <DynamicTable
      isLoading={true}
      head={head}
      rows={rows}
      rowsPerPage={5}
    />
  );
};

Empty view

Use the emptyView prop to show an empty view in the dynamic table. Empty views communicate that the table has no content to show. If there is an action that a user must take to create or show table content, add this to the empty view.

1
2
import { DynamicTable } from "@forge/react";
import { head } from "./data";

export default function TableEmpty() {
  return (
    <DynamicTable
      head={head}
      emptyView="No data to display"
    />
  );
};

Headless

Dynamic table can render without a table header if no head is supplied.

1
2
import { DynamicTable } from "@forge/react";
import { rows } from "./data";

export default function TableHeadless() {
  return (
    <DynamicTable
      rows={rows}
      rowsPerPage={5}
    />
  );
};

Pagination

Pagination is enabled or disabled by setting or unsetting the rowsPerPage prop. If the rowsPerPage prop is set and there is more than one page of content, the pagination component is added below the table.

1
2
import { DynamicTable } from "@forge/react";
import { head, rows } from "./data";

export default function TableSorted() {
  return (
    <DynamicTable
      rowsPerPage={3}
      head={head}
      rows={rows}
    />
  );
};

Drag and drop

Drag and drop functionality is built into dynamic table and is enabled using the isRankable prop. This allows you to drag rows and rank them in different orders.

1
2
import { DynamicTable } from "@forge/react";
import { rows } from "./data";

export default function TableDragAndDrop() {
  return (
    <DynamicTable
      head={head}
      rows={rows}
      rowsPerPage={5}
      isRankable
    />
  );
};

Custom column span

Individual cells can utilise colSpan to allow them to spill into other columns.

1
2
import { DynamicTable } from "@forge/react";
const days = ["Time", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday"];

const head = {
  cells: days.map((day) => ({
    key: day,
    content: day,
  })),
};

const rows = [
  {
    key: `morning-row`,
    cells: ["9:00", "Math", "History", "Science", "Computing", "Math"].map(
      (content, index) => ({
        key: index,
        content,
      })
    ),
  },
  {
    key: "midday-row",
    cells: [
      {
        key: 0,
        content: "12:00",
      },
      {
        key: 1,
        content: "LUNCH",
        colSpan: 5,
      },
    ],
  },
  {
    key: "afternoon-row",
    cells: [
      "13:00",
      "Science",
      "History",
      "Psychology",
      "Computing",
      "Business",
    ].map((content, index) => ({
      key: index,
      content,
    })),
  },
];

const CustomColSpanExample = () => (
  <DynamicTable
    caption="Class timetable"
    head={head}
    rows={rows}
  />
);

Highlighted row

Rows can be highlighted to provide additional visual prominence to a row. For example, use highlighted rows when rows are added. This should not be used to reflect selection.

1
2
import { DynamicTable } from "@forge/react";
import { head, rows } from "./data";

export default function TableHighlighted() {
  return (
    <DynamicTable
      head={head}
      rows={rows}
      rowsPerPage={5}
      highlightedRowIndex={[0, 1]}
    />
  );
};

Accessibility considerations

When using the DynamicTable component, we recommend keeping the following accessibility considerations in mind:

• Use tables to make content easier to read.
• Use only relevant text or data so that it’s easy to understand.
• Clearly label columns with simple language. This makes it easier to understand and eases screen reader navigation.
• Provide a description for complex tables. This helps the user gain context about the data. It also helps people with screen readers have an overview of the table.