@react-ui-org/react-ui
Version:
React UI is a themeable UI library for React apps.
263 lines (236 loc) ⢠7.39 kB
Markdown
# Table
Table presents complex tabular data in an easy-to-scan way.
## Basic Usage
To implement the Table component, you need to import it first:
```js
import { Table } from '@react-ui-org/react-ui';
```
And use it:
```docoff-react-preview
<Table
columns={[
{
label: 'ID',
name: 'id',
},
{
label: 'Name',
name: 'name',
},
{
format: (date) => date.toLocaleDateString('en-GB'),
label: 'Date of birth',
name: 'dateOfBirth',
},
]}
rows={[
{
dateOfBirth: new Date(1940, 10, 9),
id: 1,
name: 'John Lennon',
},
{
dateOfBirth: new Date(1942, 6, 18),
id: 2,
name: 'Paul McCartney',
},
{
dateOfBirth: new Date(1943, 2, 25),
id: 3,
name: 'George Harrison',
},
{
dateOfBirth: new Date(1940, 7, 7),
id: 4,
name: 'Richard Starkey (Ringo Starr)',
},
]}
/>
```
See [API](#api) for all available options.
## General Guidelines
- **Keep headers short** so users can quickly scan the content of the table.
Just one or two words should be enough.
- Tables are **good for displaying complex tabular data.** For simpler data sets
or even plain key-value pairs, consider using the
[Grid](/components/Grid) component.
- Tables make **lots of information easier to scan and compare.** If you have
fewer sections and want to emphasize each group more, consider using
[Cards](/components/Card).
## Responsive Tables
The easiest way to make tables responsive is to wrap them with the
[ScrollView](/components/ScrollView) component in the horizontal mode.
```docoff-react-preview
<ScrollView direction="horizontal">
<Table
columns={[
{
label: 'ID',
name: 'id',
},
{
format: (name) => (
<span style={{ whiteSpace: 'nowrap' }}>{name}</span>
),
label: 'Name',
name: 'name',
},
{
format: (note) => (
<span style={{ whiteSpace: 'nowrap' }}>{note}</span>
),
label: 'Note',
name: 'note',
},
{
format: (date) => date.toLocaleDateString('en-GB'),
label: 'Date of birth',
name: 'dateOfBirth',
},
]}
rows={[
{
dateOfBirth: new Date(1940, 10, 9),
id: 1,
name: 'John Lennon',
note: 'Lorem ipsum dolor sit amet, consectetuer adipiscing elit. '
+ 'Aenean commodo ligula eget dolor. Aenean massa. Cum sociis '
+ 'natoque penatibus et magnis dis parturient montes, nascetur '
+ 'ridiculus mus. Donec quam felis, ultricies nec, pellentesque '
+ 'eu, pretium quis, sem.',
},
{
dateOfBirth: new Date(1942, 6, 18),
id: 2,
name: 'Paul McCartney',
note: 'Lorem ipsum dolor sit amet, consectetuer adipiscing elit. '
+ 'Aenean commodo ligula eget dolor. Aenean massa. Cum sociis '
+ 'natoque penatibus et magnis dis parturient montes, nascetur '
+ 'ridiculus mus. Donec quam felis, ultricies nec, pellentesque '
+ 'eu, pretium quis, sem.',
},
{
dateOfBirth: new Date(1943, 2, 25),
id: 3,
name: 'George Harrison',
note: 'Lorem ipsum dolor sit amet, consectetuer adipiscing elit. '
+ 'Aenean commodo ligula eget dolor. Aenean massa. Cum sociis '
+ 'natoque penatibus et magnis dis parturient montes, nascetur '
+ 'ridiculus mus. Donec quam felis, ultricies nec, pellentesque '
+ 'eu, pretium quis, sem.',
},
{
dateOfBirth: new Date(1940, 7, 7),
id: 4,
name: 'Richard Starkey (Ringo Starr)',
note: 'Lorem ipsum dolor sit amet, consectetuer adipiscing elit. '
+ 'Aenean commodo ligula eget dolor. Aenean massa. Cum sociis '
+ 'natoque penatibus et magnis dis parturient montes, nascetur '
+ 'ridiculus mus. Donec quam felis, ultricies nec, pellentesque '
+ 'eu, pretium quis, sem.',
},
]}
/>
</ScrollView>
```
## Sortable Columns
The Table supports sorting indicators by adding a simple configuration.
â ď¸ The Table component only provides necessary visual support for sorting. Aside
from icons, you must **provide the comparing functionality yourself** if you
aren't rendering **already sorted data.** The reason for this decision is that
client often does not have access to the full dataset.
The following is an example of custom sorting function executed on the client.
```docoff-react-preview
React.createElement(() => {
const [tableSortColumn, setTableSortColumn] = React.useState('id');
const [tableSortDirection, setTableSortDirection] = React.useState('asc');
const [rows, setRows] = React.useState([
{
dateOfBirth: new Date(1940, 10, 9),
id: 1,
name: 'John Lennon',
},
{
dateOfBirth: new Date(1942, 6, 18),
id: 2,
name: 'Paul McCartney',
},
{
dateOfBirth: new Date(1943, 2, 25),
id: 3,
name: 'George Harrison',
},
{
dateOfBirth: new Date(1940, 7, 7),
id: 4,
name: 'Richard Starkey (Ringo Starr)',
},
]);
const compare = (items, key, direction) => {
const sortedItems = [...items];
if (key === 'id' || key === 'dateOfBirth') {
sortedItems.sort((a, b) => b[key] - a[key]);
} else if (key === 'name') {
sortedItems.sort((a, b) => {
if (a.name > b.name) {
return -1;
}
if (a.name < b.name) {
return 1;
}
return 0;
});
}
return direction === 'desc' ? sortedItems.reverse() : sortedItems;
};
const columns = [
{
isSortable: true,
label: 'ID',
name: 'id',
},
{
isSortable: true,
label: 'Name',
name: 'name',
},
{
format: (date) => date.toISOString(),
isSortable: true,
label: 'Date of birth',
name: 'dateOfBirth',
},
];
return (
<Table
columns={columns}
rows={rows}
sort={{
ascendingIcon: <rui-icon icon="up" />,
column: tableSortColumn,
descendingIcon: <rui-icon icon="down" />,
direction: tableSortDirection,
onClick: (column, direction) => {
setTableSortColumn(column);
setTableSortDirection(direction === 'asc' ? 'desc' : 'asc');
setRows(compare(rows, column, direction));
},
}}
/>
);
});
```
## Forwarding HTML Attributes
In addition to the options below in the [component's API](#api) section, you
can specify **any HTML attribute you like.** All attributes that don't
interfere with the API of the React component and that aren't filtered out by
[`transferProps`](/docs/js-helpers/transferProps) helper are forwarded to the
root `<table>` HTML element. This enables making the component interactive and
helps to improve its accessibility.
đ For the full list of supported attributes refer to:
- [`<table>` HTML element attributes][table-attributes]{:target="_blank"}
- [React common props]{:target="_blank"}
## API
<docoff-react-props src="/components/Table/Table.jsx"></docoff-react-props>
[React common props]: https://react.dev/reference/react-dom/components/common#common-props
[table-attributes]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/table#attributes