Table

A table is a specific pattern for comparing datasets in a very direct and analytical way.

install	yarn add @clayui/core
version
use	`import {Body, Cell, Head, Row, Table} from '@clayui/core';`

Table of Contents

Example
Introduction
Content
Static
Dynamic
Icons
Sorting
Asynchronous
Nested row
Expandable
Asynchronous Item
API Reference

Example

import React from 'react';
import {Body, Cell, Text, Head, Row, Table, Provider} from '@clayui/core';

export default function App() {
  const [sort, setSort] = React.useState(null);
  const [items, setItems] = React.useState([
    {files: 22, id: 1, name: 'Games', type: 'File folder'},
    {files: 7, id: 2, name: 'Program Files', type: 'File folder'},
  ]);

  const onSortChange = React.useCallback((sort) => {
    if (sort) {
      setItems((items) =>
        items.sort((a, b) => {
          let cmp = new Intl.Collator('en', {numeric: true}).compare(
            a[sort.column],
            b[sort.column]
          );

          if (sort.direction === 'descending') {
            cmp *= -1;
          }

          return cmp;
        })
      );
    }

    setSort(sort);
  }, []);

  return (
    <Provider spritemap="/icons.svg">
      <div className="p-4">
        <Table onSortChange={onSortChange} sort={sort}>
          <Head
            items={[
              {
                id: 'name',
                name: 'Name',
              },
              {
                id: 'files',
                name: 'Files',
              },
              {
                id: 'type',
                name: 'Type',
              },
            ]}
          >
            {(column) => (
              <Cell key={column.id} sortable>
                {column.name}
              </Cell>
            )}
          </Head>

          <Body defaultItems={items}>
            {(row) => (
              <Row>
                <Cell>
                  <Text size={3} weight="semi-bold">
                    {row['name']}
                  </Text>
                </Cell>
                <Cell>{row['files']}</Cell>
                <Cell>{row['type']}</Cell>
              </Row>
            )}
          </Body>
        </Table>
      </div>
    </Provider>
  );
}

Introduction

Table allows the rendering of static and dynamic content for data-oriented and data-agnostic tables to prevent the developer from having to transform their data to be able to render in a table. Composition is the central point, as is the use of the render props pattern to allow this so that the component can offer OOTB features, such as sorting and nested row.

The component covers the W3C accessibility patterns for the simplest table implementation and also the treegrid pattern for when nested row is used without requiring the developer to have to configure something extremely complex.

Warning To use the new Table implementation it is necessary to consume the component using the package @clayui/core.

Content

Content rendered in the <Table /> Menu can be done in two different ways, static and dynamic content, the choice depends on the use case.

Static

Static content is when the <Table /> options do not change during the lifecycle of the application or are hardcoded options.

Snippet

<Table>
  <Head>
    <Cell key="name">Name</Cell>
    <Cell key="type">Type</Cell>
  </Head>

  <Body>
    <Row>
      <Cell>Games</Cell>
      <Cell>File Folder</Cell>
    </Row>
    <Row>
      <Cell>Program Files</Cell>
      <Cell>File Folder</Cell>
    </Row>
  </Body>
</Table>

Dynamic

Unlike static content, dynamic content is when the options can change during the lifecycle of the application or when the data comes from a service. Dynamic content rendering is data agnostic, this allows you to configure how to render the component options regardless of the chosen data structure. For more information about controlled and uncontrolled components, visit this blog post.

Snippet

<Table>
  <Head
    items={[
      {
        id: '1',
        name: 'Name',
      },
      {
        id: '2',
        name: 'Type',
      },
    ]}
  >
    {(column) => <Cell key={column.id}>{column.name}</Cell>}
  </Head>

  <Body
    items={[
      {id: 1, name: 'Games', type: 'File folder'},
      {id: 2, name: 'Program Files', type: 'File folder'},
    ]}
    onItemsChange={() => {
      // do something
    }}
  >
    {(row) => (
      <Row>
        <Cell>{row.name}</Cell>
        <Cell>{row.type}</Cell>
      </Row>
    )}
  </Body>
</Table>

Icons

Warning When implementing ClayTable from a React application, the icons may not render. The Application Provider method will make the icons available for use.

Snippet

<Provider spritemap={spritemap}>
  <Table>
    <Head
      items={[
        {
          id: '1',
          name: 'Name',
        },
        {
          id: '2',
          name: 'Type',
        },
      ]}
    >
      {(column) => <Cell key={column.id}>{column.name}</Cell>}
    </Head>

    <Body
      defaultItems={[
        {id: 1, name: 'Games', type: 'File folder'},
        {id: 2, name: 'Program Files', type: 'File folder'},
      ]}
    >
      {(row) => (
        <Row>
          <Cell>{row.name}</Cell>
          <Cell>{row.type}</Cell>
        </Row>
      )}
    </Body>
  </Table>
</Provider>

Sorting

Column sorting is implemented OOTB so the developer doesn’t need to worry about implementing the UI details but the developer still needs to add their filter layer since the component is data-agnostic and allows you to do this asynchronously, it is important, especially when your data is paged, that the filter must happen in the backend.

It is also possible to implement your own logic on the client side when your data is predictable, check out the pseudocode.

Info Column sorting is only enabled for columns that contain the


sortable

API defined.

import React from 'react';
import {Body, Cell, Text, Head, Row, Table, Provider} from '@clayui/core';

export default function App() {
  const [sort, setSort] = React.useState(null);
  const [items, setItems] = React.useState([
    {files: 22, id: 1, name: 'Games', type: 'File folder'},
    {files: 7, id: 2, name: 'Program Files', type: 'File folder'},
  ]);

  const filteredItems = React.useMemo(() => {
    if (!sort) {
      return items;
    }

    return items.sort((a, b) => {
      let cmp = new Intl.Collator('en', {numeric: true}).compare(
        a[sort.column],
        b[sort.column]
      );

      if (sort.direction === 'descending') {
        cmp *= -1;
      }

      return cmp;
    });
  }, [sort, items]);

  return (
    <Provider spritemap="/icons.svg">
      <div className="p-4">
        <Table onSortChange={setSort} sort={sort}>
          <Head>
            <Cell key="name" sortable>
              Name
            </Cell>
            <Cell key="files" sortable>
              Files
            </Cell>
            <Cell key="type" sortable>
              Type
            </Cell>
          </Head>

          <Body defaultItems={filteredItems}>
            {(row) => (
              <Row>
                <Cell>
                  <Text size={3} weight="semi-bold">
                    {row['name']}
                  </Text>
                </Cell>
                <Cell>{row['files']}</Cell>
                <Cell>{row['type']}</Cell>
              </Row>
            )}
          </Body>
        </Table>
      </div>
    </Provider>
  );
}

Asynchronous

Most tables with sorting can have a lot of data and are paged so the sorting must happen on the server side instead of implementing the logic on the client side. You can achieve this level of implementation by composing using the useResource hook.

Snippet

function App() {
  const {
    resource: items,
    sort,
    sortChange,
  } = useResource({
    fetch: (link, init, sort) => {
      const url = new URL(link);

      if (sort) {
        url.searchParams.append('column', String(sort.column));
        url.searchParams.append('direction', sort.direction);
      }

      return fetch(url, init);
    },
    link: 'https://example.com/api/items',
  });

  return (
    <Table onSortChange={setSort} sort={sort}>
      <Head>
        <Cell key="name" sortable>
          Name
        </Cell>
        <Cell key="files" sortable>
          Files
        </Cell>
        <Cell key="type">Type</Cell>
      </Head>

      <Body defaultItems={items}>...</Body>
    </Table>
  );
}

Nested row

Implementing nested row allows you to render a table as a tree view. It is not necessary that you have to change your composition to render in tree view but just configure the nestedKey property to inform which nested key and the composition can continue in the same way.

When using the nested row pattern, Clay automatically changes the accessibility behavior to use the treegrid recommendation instead of the default behavior.

Limitation The unique id of a row does not work properly when configured via

key

in the Row component property to deal with the nodes expandability, it is necessary that the

id

key is defined in your row data to use as unique id.

import React from 'react';
import {Body, Cell, Head, Row, Table, Provider} from '@clayui/core';

export default function App() {
  const columns = [
    {
      id: 'name',
      name: 'Name',
    },
    {
      id: 'type',
      name: 'Type',
    },
  ];

  return (
    <Provider spritemap="/icons.svg">
      <div className="p-4">
        <Table aria-label="Drive" nestedKey="children">
          <Head items={columns}>
            {(column) => (
              <Cell className="table-cell-minw-300" key={column.id}>
                {column.name}
              </Cell>
            )}
          </Head>

          <Body
            defaultItems={[
              {
                children: [{id: 10, name: 'WoW', type: 'MMORPG'}],
                id: 1,
                name: 'Games',
                type: 'File folder',
              },
              {
                id: 2,
                name: 'Program Files',
                type: 'File folder',
              },
            ]}
          >
            {(row) => (
              <Row items={columns}>
                {(column) => (
                  <Cell key={row.id + ':' + column.id}>{row[column.id]}</Cell>
                )}
              </Row>
            )}
          </Body>
        </Table>
      </div>
    </Provider>
  );
}

Expandable

Expanding nodes is done OOTB in the component but it is also possible to control the state to modify behaviors if necessary or use it to save a session to improve the user experience.

Warning If your data structure does not have a key property

id

that is used as a unique identifier for each item, you need to configure which key will be used to identify the item by using the


itemIdKey

API in the Table component.

Snippet

const [expandedKeys, setExpandedKeys] = useState(new Set());

<Table expandedKeys={expandedKeys} onExpandedChange={setExpandedKeys}>
  <Head items={columns}>
    {(column) => <Cell key={column.id}>{column.name}</Cell>}
  </Head>

  <Body defaultItems={rows}>
    {(row) => (
      <Row items={columns}>
        {(column) => (
          <Cell key={`${row.id}:${column.id}`}>{row[column.id]}</Cell>
        )}
      </Row>
    )}
  </Body>
</Table>;

Asynchronous Item

When the tree is very large with a lot of data on a single node, loading the data asynchronously is essential to reduce the initial data payload and memory space. Table supports asynchronous node loading when the user expands a node.

When returning void , null or undefined the Table will do nothing.
When returning the items will add to the tree.

Warning If you have an error in the asynchronous call of the


onLoadMore

method, only the suppression is done and an error is thrown on the console.

When adding a new asynchronous item to the tree, the onItemsChange method is respectively called to update the tree with a new value if the items prop is controlled.

Snippet

<Table
  onLoadMore={async (item) => {
    return await fetch(`example.com/tree/item?parent_id=${item.id}`);
  }}
>
  <Head items={columns}>
    {(column) => <Cell key={column.id}>{column.name}</Cell>}
  </Head>

  <Body
    defaultItems={[
      {id: 1, name: 'Games', type: 'File folder'},
      {id: 2, name: 'Program Files', type: 'File folder'},
    ]}
  >
    {(row) => (
      <Row>
        <Cell>{row.name}</Cell>
        <Cell>{row.type}</Cell>
      </Row>
    )}
  </Body>
</Table>

API Reference

Table

React.ForwardRefExoticComponent<IProps & React.RefAttributes<HTMLTableElement>>

Parameters

Properties

alwaysVisibleColumns

Set<React.Key> | undefined

Defines the columns that are always visible and will be ignored by the visible columns functionality.

columnsVisibility

boolean | undefined

Flag to enable column visibility control.

defaultExpandedKeys

Set<React.Key> | undefined

Property to set the initial value of expandedKeys (uncontrolled).

defaultSort

Sorting | null | undefined

Default state of sort (uncontrolled).

defaultVisibleColumns

Map<React.Key, number> | undefined

Default value for visible columns in the table (uncontrolled).

expandedKeys

Set<React.Key> | undefined

The currently expanded keys in the collection (controlled).

visibleColumns

Map<React.Key, number> | undefined

Defines which columns are visible in the table (controlled).

messages

{ columnsVisibility: string; columnsVisibilityDescription: string; columnsVisibilityHeader: string; expandable: string; sortDescription: string; sorting: string; } | undefined

Texts used for assertive messages to SRs.

onExpandedChange

((keys: Set<React.Key>) => void) | undefined

A callback that is called when items are expanded or collapsed (controlled).

onLoadMore

((item: unknown) => Promise<Array<any> | undefined>) | undefined

When a tree is very large, loading items (nodes) asynchronously is preferred to decrease the initial payload and memory space. The callback is called every time the item is a leaf node of the tree.

onSortChange

((sorting: Sorting | null) => void) | undefined

Callback for when the sorting change (controlled).

onVisibleColumnsChange

((columns: Map<React.Key, number>) => void) | undefined

Callback called when columns visibility changes (controlled).

sort

Sorting | null | undefined

Current state of sort (controlled).

nestedKey

string | undefined

Flag to indicate which key name matches the nested rendering of the tree.

itemIdKey

string | undefined

Defines which key should be used as the item identifier.

size

"sm" | "lg" | undefined

Defines the size of the table.

bodyVerticalAlignment

"bottom" | "middle" | "top" | undefined

This property vertically align the contents inside the table body according a given position.

borderedColumns

boolean | undefined

Applies a Bordered style on Table’s columns.

borderless

boolean | undefined

Removes the default border and rounded corners from table.

headingNoWrap

boolean | undefined

This property keeps all the headings on one line.

headVerticalAlignment

"bottom" | "middle" | "top" | undefined

This property vertically align the contents inside the table header according a given position.

hover

boolean | undefined

Applies a Hover style on Table.

noWrap

boolean | undefined

This property enables keeping everything on one line.

responsive

boolean | undefined

Turns the table responsive.

responsiveSize

"sm" | "lg" | "md" | "xl" | undefined

Defines the responsive sizing.

striped

boolean | undefined

Applies a Striped style on Table.

tableVerticalAlignment

"bottom" | "middle" | "top" | undefined

This property vertically align the contents inside the table according a given position.

Returns

ReactElement<any, string | JSXElementConstructor<any>> | null

Body

<T extends Record<string, any>>({ children, defaultItems, items: outItems, onItemsChange, ...otherProps }: IProps<T>, ref: React.Ref<HTMLTableSectionElement>) => JSX.Element

Parameters

*

IProps<T>

children *

React.ReactNode | ((item: T, index?: number) => React.ReactElement)

Children content to render a dynamic or static content.

defaultItems

Array<T> | undefined

Property to set the initial value of items (uncontrolled).

items

Array<T> | undefined

Property to render content with dynamic data (controlled).

onItemsChange

((items: Array<T>) => void) | undefined

A callback which is called when the property of items is changed (controlled).

ref *

React.Ref<HTMLTableSectionElement>

Returns

Element

Head

<T extends Record<string, any>>({ children, items, ...otherProps }: IProps<T>, ref: React.Ref<HTMLTableSectionElement>) => JSX.Element

Parameters

*

IProps<T>

children *

React.ReactNode | ((item: T, index?: number) => React.ReactElement)

Children content to render a dynamic or static content.

items

Array<T> | undefined

Property to render content with dynamic data.

ref *

React.Ref<HTMLTableSectionElement>

Returns

Element

Cell

React.ForwardRefExoticComponent<IProps & React.RefAttributes<HTMLTableCellElement>>

Parameters

Properties

align

"center" | "left" | "right" | undefined

Aligns the text inside the Cell.

children *

React.ReactNode

Children content to render content.

delimiter

"end" | "start" | undefined

Sometimes we are unable to remove specific table columns from the DOM and need to hide it using CSS. This property can be added to the “new” first or last cell to maintain table styles on the left and right side.

expanded

boolean | undefined

Fills out the remaining space inside a Cell.

sortable

boolean | undefined

Whether the column allows sortable. Only available in the header column.

textAlign

"center" | "end" | "start" | undefined

Aligns horizontally contents inside the Cell.

truncate

boolean | undefined

Truncates the text inside a Cell.

wrap

boolean | undefined

width

string | undefined

Sets the column width.

textValue

string | undefined

Sets a text value if the component’s content is not plain text.

Returns

ReactElement<any, string | JSXElementConstructor<any>> | null

Row

<T extends Record<string, any>>({ _expandable, _index, _item, _level, _loc, _size, children, className, delimiter, divider, items, keyValue, lazy, ...otherProps }: IProps<T>, outRef: React.Ref<HTMLTableRowElement>) => JSX.Element

Parameters

*

IProps<T>= {"divider":false,"lazy":false}

children *

React.ReactNode | ((item: T, index?: number) => React.ReactElement)

Children content to render a dynamic or static content.

delimiter

"end" | "start" | undefined

This property can be added to the “new” first or last ClayTable.Row to maintain table styles on the top and bottom sides.

divider

boolean | undefined

Applies a divider style inside the row.

items

Array<T> | undefined

Property to render content with dynamic data.

lazy

boolean | undefined

Flag to indicate that the row has children to be loaded lazily when onLoadMore is set.

outRef *

React.Ref<HTMLTableRowElement>

Returns

Element

Edit this page on GitHub

Contributors

Matuzalém Teles, Patrick Yeo, Selena Aungst

Last edited May 9, 2025 at 6:15:38 AM

Table of Contents

Example
Introduction
Content
Static
Dynamic
Icons
Sorting
Asynchronous
Nested row
Expandable
Asynchronous Item
API Reference