@asphalt-react/table v2.0.0-rc.4

Table

Table displays large amount of information in a way that's easy to read. You can create complex designs by bringing components like Avatar, Tag & Checkbox to the Table. The Table family has sub-components like TableBody & TableBodyCell to show tabular data. The Table offers different sizes and styles to customize its appearance. You can also freeze some rows which is helpful to browse when there are lots of rows.

The architecture of the Table components is flexible, so you can bring your own data and compose complex table functionality as needed.

Usage

import {
  Table,
  TableHead,
  TableBody,
  TableHeadRow,
  TableBodyRow,
  TableHeadCell,
  TableBodyCell
} from "@asphalt-react/table";

<Table>
  <TableHead>
    <TableHeadRow>
      <TableHeadCell>First Name</TableHeadCell>
      <TableHeadCell>Last Name</TableHeadCell>
      <TableHeadCell>Email</TableHeadCell>
    </TableHeadRow>
  </TableHead>
  <TableBody>
    <TableBodyRow>
      <TableBodyCell>John</TableBodyCell>
      <TableBodyCell>Kennedy</TableBodyCell>
      <TableBodyCell>john@random.com</TableBodyCell>
    </TableBodyRow>
    <TableBodyRow>
      <TableBodyCell>George</TableBodyCell>
      <TableBodyCell>Bush</TableBodyCell>
      <TableBodyCell>george@random.com</TableBodyCell>
    </TableBodyRow>
  </TableBody>
</Table>

Building blocks

1. The Table component comes with:
   • TableHead
   • TableHeadRow
   • TableHeadCell
   • TableHeadCellText
   • TableHeadCellIcon
   • TableHeadCellAction
   • TableBody
   • TableBodyRow
   • TableBodyCell
2. The cell components (TableBodyCell & TableHeadCell) supports 3 sizes: small, medium & large.
3. You can (left, center or right) align text content in the cell components.

Hooks

Use the useTable() hook to get all the prop getter functions and then spread them in the right children components. Pass all the props in the useTable() hook as parameter.

import {
  useTable,
  /* other component imports */
}
const {
  getTableProps,
  getHeadCellProps,
  getBodyCellProps
} = useTable(props);

<Table {...getTableProps()}>
  <TableHead>
    <TableHeadRow>
      <TableHeadCell {...getHeadCellProps()}>Name</TableHeadCell>
      <TableHeadCell {...getHeadCellProps()}>Age</TableHeadCell>
    </TableHeadRow>
  </TableHead>
  <TableBody>
    <TableBodyRow>
      <TableBodyCell {...getBodyCellProps()}>John Kennedy</TableBodyCell>
      <TableBodyCell {...getBodyCellProps()}>43</TableBodyCell>
    </TableBodyRow>
    <TableBodyRow>
      <TableBodyCell {...getBodyCellProps()}>George Bush</TableBodyCell>
      <TableBodyCell {...getBodyCellProps()}>56</TableBodyCell>
    </TableBodyRow>
  </TableBody>
</Table>

Cell appearance

The table cells has 3 appearances to create distinction between them:

1. Enclosed (default): Adds borders on all sides of the TableBodyCell & TableHeadCell.
2. Fenced: Separates each TableBodyCell vertically with a border on the bottom side.
3. Nude: No visual distinction between the TableCells.

Prop collision

If you set multiple competing props like alignment, most components will fallback to the default prop value. For example:

<TableBodyCell rightAlign centerAlign>Foo bar</TableBodyCell>

In this case, the TableBodyCell will fallback to leftAlign.

Selecting a row

TableBodyRow component accepts a selected prop to make it look like selected.

Accessibility

1. All components in the table family support HTML table attributes
2. All components in the table family support aria-/* attributes associated with role="table

Table

Props

children

Content to render inside the Table.

contentFit

Enables the Table's content to dictate its width.

Disabling contentFit wraps the Table with a wrapper and adds a scroll if the content overflows.

TableHead

Props

children

React node to render rows inside the TableHead

TableHeadRow

Props

children

React nodes to render cells in table head.

sticky

Enable sticky behaviour for TableHeadRow

Note: This only works when contentFit is enabled in Table

TableHeadCell

Props

children

React node to render the contents.

leftAlign

Left align contents.

rightAlign

Right align contents.

centerAlign

Center align contents.

enclosed

Adds borders on all sides of the TableHeadCell. This is the default.

fenced

Separates each TableHeadCell vertically with a border on the bottom side.

nude

Doesn't render a border on the cells.

size

Size of the TableHeadCell. Accepts "s", "m", "l" for small, medium & large.

TableHeadCellText

Props

children

React node to render the text content.

TableHeadCellIcon

Props

children

Icon to enhance the head cell's text. Accepts SVG.

TableHeadCellAction

Props

children

React node to accept actionable elements such as a sort button.

TableBody

Props

children

React node to render rows inside the TableBody.

TableBodyRow

Props

children

React nodes to render cells in table body.

selected

Makes the row look like selected.

sticky

Enable sticky behaviour for TableBodyRow.

Note: This only works when contentFit is enabled in Table.

TableBodyCell

Props

children

React node to render the contents.

leftAlign

Left align contents.

rightAlign

Right align contents.

centerAlign

Center align contents.

enclosed

Adds borders on all sides of the TableBodyCell. This is the default.

fenced

Separates each TableBodyCell vertically with a border on the bottom side.

nude

Doesn't render a border on the cells.

size

Size of the TableBodyCell. Accepts "s", "m", "l" for small, medium & large.

useTable

React hook which returns prop getter functions. Use these functions to generate prop objects for different components in Table.

Arguments

UseTable accepts the following props:

1. ContentFit
2. Size
3. Enclosed
4. Fenced
5. Nude

Getter functions

getTableProps()

Use this function to create props for Table component.

const { getTableProps } = useTable({ contentFit: true });

<Table {...getTableProps({ id: "main-table" })}>
  /* contents of the table */
</Table>

getHeadCellProps()

Use this function to create props for TableHeadCell component.

const { getHeadCellProps } = useTable({ fenced: true, size: "l" });

<Table>
  <TableHead>
    <TableHeadRow>
      <TableHeadCell {...getHeadCellProps()}>Name</TableHeadCell>
      <TableHeadCell {...getHeadCellProps()}>Phone</TableHeadCell>
    </TableHeadRow>
  </TableHead>

  /* rest of the contents */
</Table>

getBodyCellProps()

Use this function to create props for TableBodyCell component.

const { getBodyCellProps } = useTable({ nude: true, size: "s" });

<Table>
  /* table head */

  <TableBody>
    <TableBodyRow>
      <TableBodyCell {...getBodyCellProps()}>John</TableBodyCell>
      <TableHeadCell {...getBodyCellProps()}>active</TableHeadCell>
    </TableBodyRow>
    <TableBodyRow>
      <TableBodyCell {...getBodyCellProps()}>Peter</TableBodyCell>
      <TableHeadCell {...getBodyCellProps()}>paused</TableHeadCell>
    </TableBodyRow>
  </TableBody>

  /* rest of the contents */
</Table>