@asphalt-react/table

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>[e-mail]</TableBodyCell>
    </TableBodyRow>
    <TableBodyRow>
      <TableBodyCell>George</TableBodyCell>
      <TableBodyCell>Bush</TableBodyCell>
      <TableBodyCell>[e-mail]</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

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>

Props

children

Content to render inside the Table.

type	required	default
node	true	N/A

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.

type	required	default
bool	false	false

TableHead

Props

children

React node to render rows inside the TableHead

type	required	default
node	false	N/A

TableHeadRow

Props

children

React nodes to render cells in table head.

type	required	default
node	false	N/A

sticky

Enable sticky behaviour for TableHeadRow

Note: This only works when contentFit is enabled in Table

type	required	default
bool	false	false

TableHeadCell

Props

children

React node to render the contents.

type	required	default
node	true	N/A

leftAlign

Left align contents.

type	required	default
bool	false	false

rightAlign

Right align contents.

type	required	default
bool	false	false

centerAlign

Center align contents.

type	required	default
bool	false	false

enclosed

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

type	required	default
bool	false	false

fenced

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

type	required	default
bool	false	false

nude

Doesn't render a border on the cells.

type	required	default
bool	false	false

size

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

type	required	default
enum	false	"m"

TableHeadCellText

Props

children

React node to render the text content.

type	required	default
node	true	N/A

TableHeadCellIcon

Props

children

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

type	required	default
node	true	N/A

TableHeadCellAction

Props

children

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

type	required	default
node	true	N/A

TableBody

Props

children

React node to render rows inside the TableBody.

type	required	default
node	false	N/A

TableBodyRow

Props

children

React nodes to render cells in table body.

type	required	default
node	false	N/A

selected

Makes the row look like selected.

type	required	default
bool	false	false

sticky

Enable sticky behaviour for TableBodyRow.

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

type	required	default
bool	false	false

TableBodyCell

Props

children

React node to render the contents.

type	required	default
node	true	N/A

leftAlign

Left align contents.

type	required	default
bool	false	false

rightAlign

Right align contents.

type	required	default
bool	false	false

centerAlign

Center align contents.

type	required	default
bool	false	false

enclosed

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

type	required	default
bool	false	false

fenced

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

type	required	default
bool	false	false

nude

Doesn't render a border on the cells.

type	required	default
bool	false	false

size

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

type	required	default
enum	false	"m"