BRAID
Braid Logo
 

Table

A structure of rows and columns that allows users to easily view, compare and analyse a dataset.
LoremIpsumDolor
SitAmetConsectetur
AdipiscingElitPraesent
SemperInterdumViverra
Open in Playroom

Accessibility

Follows the WAI-ARIA Table Pattern.All Table components require an accessible name describing the data represented within. This must be provided using the label prop.

Table structure

A Table is made up of three sections: TableHeader, TableBody (required) and TableFooter, each section containing one or more TableRow components. Each row is made of up of TableCell or TableHeaderCell components representing each column of the data.
Table
TableHeader
TableRow
TableHeaderCell
TableHeaderCell
TableHeaderCell
TableBody (required)
TableRow
TableCell
TableCell
TableCell
TableFooter
TableRow
TableCell
TableCell
TableCell

Visual guidelines

  • Keep it simple and limit colour usage. Avoid over-styling content or displaying unnecessary components within the table. In most cases using Text and TextLink should suffice.
  • Avoid placing your table inside a bounded box or Card. Instead, place it directly onto the page surface.
  • Give each piece of data it’s own column, avoid showing multiple pieces of data in a single column.
  • Left align textual data and right align numerical data.
  • Keep column headers short, a few words at most.

Column headers

A TableHeader can be provided containing a TableRow of TableHeaderCell components to provide the relevant semantics, column labelling and styling.
LoremIpsumDolor
SitAmetConsectetur
AdipiscingElitPraesent
SemperInterdumViverra
Open in Playroom

Row headers

Row-level headers are supported by providing a TableHeaderCell within a TableRow of the TableBody section.
SitAmetConsectetur
AdipiscingElitPraesent
SemperInterdumViverra
Open in Playroom
A table may also combine both column headers and row headers.
Time
LoremIpsumDolor
09:00-10:00SitAmetConsectetur
10:00-11:00AdipiscingElitPraesent
11:00-12:00SemperInterdumViverra
Open in Playroom

Footers

A TableFooter can be provided, containing a TableRow wrapping TableCell components, providing the relevant semantics and styling.
LoremIpsumDolor
SitAmetConsectetur
AdipiscingElitPraesent
SemperInterdumViverra
QuisTemporVoluptate
Open in Playroom

Table width

Tables display at full width of their container with columns expanding to fill available space. When a table is wider than the available space, it scrolls horizontally to retain its structure and allow easy comparison of data. This behaviour also applies on mobile and tablet.
LoremIpsumDolorSitAmetConsecteturPharetra
Adipiscing elitPraesent semperInterdum viverraSed convallis Phasellus condimentumCras finibusRutrum lacinia
Donec iberoErat facilisisQuis dictumQuisque lobortisAenean bibendumMaximus nequeGravida imperdiet
Nullam rhoncusTellus vestibulumPurus vitaePorttitor sapienMorbi cursusOdio aliquetCommodo quisque
Open in Playroom

Column widths

By default, a TableCell and TableHeaderCell have a width of auto, sizing based on the column’s longest content and distributing any additional space automatically.A cell can be made as small as possible by setting its width to content — recommended for status and actions columns.Alternatively, the distribution of excess space can be weighted by providing a percentage value to the width prop — useful for increasing the focus on priority columns.
“content”“30%”“auto”“auto”
“content”
BadgeSitAmetConsectetur
BadgeAdipiscingElitPraesent
BadgeSemperInterdumViverra
Open in Playroom
Additionally, limits can be provided to column widths via the minWidth and maxWidth props, which accept a number (in pixels).The minWidth prop can be used to prevent a column from becoming too small. This is useful for maintaining hierachy when there is less available space, i.e. smaller screen sizes.The maxWidth prop is useful for constraining columns with long data, ensuring content is truncated when it exceeds the specified width. As a convenience when setting a maxWidth, all Text components in the column will default maxLines to a single line.
minWidth=150maxWidth=200maxWidth & width
“content”
SitAmetAmet
ElitAdipiscing incididunt amet id laborum minimAdipiscing incididunt amet id laborum minim
SemperInterdumInterdum
Open in Playroom

Vertical alignment

The vertical alignment of content within rows can be configured using the alignY prop on Table.Supported alignments are center (default) and top.
“center”
LoremIpsumDolor
ContentContent
ContentContent
ContentContent
ContentContent
“top”
LoremIpsumDolor
ContentContent
ContentContent
ContentContent
ContentContent
Open in Playroom

Horizontal alignment

The horizontal alignment of content within cells can be configured using the align prop on TableCell and TableHeaderCell components.Supported alignments are left (default), center and right.
“left”
“center”
“right”
Sit
Amet
Consectetur
Adipiscing
Elit
Praesent
Open in Playroom

Wrapping

By default, all TableCell and TableHeaderCell components are prevented from wrapping their content. This keep rows a consistent height and means the content can influence the column width.If desired, wrapping can be enabled by setting the wrap prop to true on a per-cell basis.
LoremIpsumDolor
Id nisi consequat enim exercitation non fugiat ipsum ut ea.Incididunt eu anim eu pariatur dolore dolore fugiat qui ipsum tempor ex laborum voluptate sint.Culpa labore minim consectetur ut officia ea ea cupidatat excepteur ipsum.
AdipiscingElitPraesent
Open in Playroom

Column spanning

Both TableCell and TableHeaderCell can span across multiple columns by providing the number of columns via the colspan prop.
LoremIpsumDolor
SitAmetConsectetur
AdipiscingElitPraesent
Culpa labore minim consectetur ut officia ea ea cupidatat excepteur.Tempor
Open in Playroom

Column visibility

Columns can be hidden responsively using the hideBelow and/or hideAbove prop, by specifying the name of the breakpoint, e.g. hideBelow=“tablet”, on the column header.Consider the three column table below, applying hideBelow=“tablet” to the second column header. Three columns will be shown from the tablet breakpoint upwards, and the second column will be hidden on mobile.
On “tablet” and above
LoremIpsumDolor
SitAmetConsectetur
AdipiscingElitPraesent
Below “tablet”
LoremDolor
SitConsectetur
AdipiscingPraesent
Open in Playroom

When to use

Use a Table:
  • To display a dataset in a structured way using rows and columns
  • To allow users to easily view, compare and analyse a dataset
  • When your dataset is primarily numerical.
Don’t use a Table:
  • To display a simple list of items (use a List instead)
  • To layout content on a page (use layout components instead).

Data attributes

Braid components are very explicit about the properties they accept, which makes providing arbitrary data attributes not possible. Instead, a data prop can be provided as a single collection of data attributes.
<Table
  data={{ testid: 'table-1' }}
  // => data-testid="table-1"
>
  <TableHeader data={{ testid: 'table-header-1' }}>
    <TableRow data={{ testid: 'table-row-1' }}>
      <TableHeaderCell data={{ testid: 'table-header-cell-1' }}>
        ...
      </TableHeaderCell>
    </TableRow>
  </TableHeader>
  <TableBody data={{ testid: 'table-body-1' }}>
    <TableRow>
      <TableCell data={{ testid: 'table-cell-1' }}>
        ...
      </TableCell>
    </TableRow>
  </TableBody>
  <TableFooter data={{ testid: 'table-footer-1' }}>
    ...
  </TableFooter>
</Table>
Open in Playroom