Skip to main content

Pivotal UI

v18.0.0

Tables

The Table component is a robust component that offers a styled table. If the rows change, the content on the page will update.

Several enhanced Table components are also available:

  • SortableTable: rows can be sorted ascending or descending by a chosen column.
  • FlexTable: uses div tags to compose a table rather than traditional HTML tags.
  • SortableFlexTable: a SortableTable that is composed of div tags.
  • AdvancedTable: a Table that includes all plugins
Basic HTML Table with implicit columns

When no columns prop is given, the table will automatically determine the columns and column headers based on the keys of data.

ReferenceError: React is not defined
Basic HTML Table with simple columns

When the columns prop contains strings, the associated data will be shown in the data in the order provided.

ReferenceError: React is not defined
Sortable HTML Table with explicit columns

The columns prop defines the properties of each column. This allows for more complex table behavior, such as sorting.

ReferenceError: React is not defined
Basic Flex Table
ReferenceError: React is not defined
Sortable Flex Table
ReferenceError: React is not defined
Table row hover

Adding .tr-hover to a specific table row or the table element itself will add the hover effect.

ReferenceError: withRowClassName is not defined
Table cell hover

Adding .td-hover to the table element will allow the user to highlight individual cells.

ReferenceError: React is not defined
Table border modifiers

Remove all of the internal horizontal borders with class .tr-no-h-borders applied to the table row or the table element.

ReferenceError: React is not defined
No external borders

No external borders to rows using class .table-no-ext-borders on the table element.

ReferenceError: React is not defined
No borders

No borders to rows using class .table-no-borders on the table element.

ReferenceError: React is not defined

Using plugins

The base Table component has a limited feature-set. Users can compose Tables with additional features by using plugins.

Here are the plugins provided by Pivotal UI:

  • withCellClassName
  • withCellEllipsis
  • withCellOnClick
  • withCellTooltip
  • withCellWidth
  • withFlex
  • withFooterRow
  • withRenderTdChildren
  • withRenderThChildren
  • withRowClassName
  • withRowDrawer
  • withRowLink
  • withScrollableTbody
  • withSorting

A composed table can be created by composing one or more of the above plugins:

import {withFlex, withSorting, Table} from 'pivotal-ui/react/table';
const ComposedTable = withFlex(withSorting(Table));
ReactDOM.render(<ComposedTable columns={columns} data={data}/>

Or with lodash.flow:

import flow from 'lodash.flow';
const ComposedTable = flow(withFlex, withSorting)(Table);

The following examples demonstrate the individual usage of each of the above plugins.

Flex

Flex tables are composed of div tags.

ReferenceError: withFlex is not defined
Cell links (requires FlexTable)

Each cell in a column of a FlexTable can be an <a> tag. In this example, the first column links to the top of this section, and the last column links to the top of this page.

ReferenceError: withCellLink is not defined
Cell className

Each cell in a column can have custom classes. In this example, the first column has the h4 class applied.

ReferenceError: withCellClassName is not defined
Row className

A className can be provided to a row element. In this example, the body rows are given the h4 class.

ReferenceError: withRowClassName is not defined
Cell ellipsis (requires FlexTable)

Each cell in a column of a FlexTable can be set to trail off with an ellipsis when the contents exceed the available space. In this example, the first column has the type-ellipsis class applied.

ReferenceError: withCellEllipsis is not defined
Cell onClick

Each cell in a column can be provided an onClick handler. In this example, the first column has the will show an alert with contextual information for the row when clicked.

ReferenceError: withCellOnClick is not defined
Custom renderTdChildren function

Each cell in a column can provide a custom render function. In this example, the first column has a custom child render function that capitalizes its text.

ReferenceError: withRenderTdChildren is not defined
Custom renderThChildren function

Each header in a column can provide a custom render function. In this example, the first header has a custom child render function that capitalizes its text.

ReferenceError: withRenderThChildren is not defined
Cell tooltip

Each cell in a column can have a tooltip. In this example, the first column has a tooltip that displays its text, reversed. The header tooltip has a dark theme, while the body cell tooltips have a light theme.

ReferenceError: withCellTooltip is not defined
Cell width

Each cell in a column can have a fixed width. In this example, the cells in the first column are 100px wide, and the cells in the second column are 200px. The cells in the final column use the remaining space.

ReferenceError: withCellWidth is not defined
Footer row

A custom footer row can be provided.

ReferenceError: withFooterRow is not defined
Row drawer (requires FlexTable)

When body rows of a FlexTable are clicked, drawer content is revealed.

ReferenceError: withRowDrawer is not defined
Row links (requires FlexTable)

An entire row of a FlexTable can be rendered as an <a> tag. In this example, clicking the first body row links to Table usage.

ReferenceError: withRowLink is not defined
Sorting

A table can be sorted ascending or descending by a given column by clicking on that column's header.

ReferenceError: withSorting is not defined
Scrollable table body (requires FlexTable)

When scrollable and tbodyHeight="<some height>", the table body will scroll when that height is exceeded.

ReferenceError: withScrollableTbody is not defined

Writing plugins

The Table component renders the following DOM elements: table, thead, tbody, tfoot, tr, th, td.

Table plugins provide the ability to:

  1. inspect and inject new props
  2. use a custom DOM element or React component in place of one of the above standard table elements

In order to write a new plugin:

  1. Create a new file that imports TablePlugin from pivotal-ui/react/table.

    import {TablePlugin} from 'pivotal-ui/react/table';
  2. Export a function that takes a Table argument:

    export function withCellColor(Table) { /* ... */ }
  3. Inside the function, return a class that extends TablePlugin:

    return class TableWithCellColor extends TablePlugin { /* ... */}
  4. In the class, define a render function that returns the result of calling this.renderTable with the Table argument, and an Object:

    render() {
    return this.renderTable(Table, { /* ... */ }
    }

The Object can contain any of the following keys:

  • Tag keys: tableTag, theadTag, tbodyTag, tfootTag, trTag, thTag, tdTag
  • Prop keys: table, thead, tbody, tfoot, tr, th, td

The value should be a callback.

For Tag callbacks, relevant context is passed as an argument. The callback should return a new DOM element as a String or a React Component to be used in place of the standard HTML element.

For Prop callbacks, the first argument is the props that the element will receive. The second argument is relevant context. The callback should return any new props that the element should be rendered with. They will generally overwrite any pre-existing props. The className and style props will be merged with the old values.

Table with cell color

Each column has a different color: red, green, and blue.

ReferenceError: Table is not defined

For additional examples, review the plugins that Pivotal UI provides.

Table modifiers

ClassDescription
.tableApplied to the starting element to define the style standards.
.tr-hoverApplied to the starting table element or the desired row to add the hover effect.
.td-hoverApplied to the starting .table element to change the table row hover effect to a table cell hover.
.tr-no-h-bordersRemoves inner horizontal borders from the desired .table or table row element.
.table-no-ext-bordersRemoves external borders for the entire table when applied to the .table element.
.table-no-bordersRemoves all borders, internal and external, when applied to the .table element.Removes all borders, internal and external, when applied to the .table element.
.table-td-palApplied to table cell to add 8px vertical padding
.table-td-paxlApplied to table cell to add 16px vertical padding

Props

Table props

PropertyRequiredTypeDefaultDescription
columnsnoArrayMetadata about columns
datayesArrayThe data to display in the table
footerRownoAnyAnything that evaluates into HTML. Only valid when used with withFooterRow plugin.
rowClassNamenoFunctionFunction with input ({rowDatum, isHeader, rowIndex}) and outputs a string. Only valid when used with withRowClassName plugin.
rowDrawernoFunctionFunction with input (rowIndex). Only valid when used with withRowDrawer plugin.
rowLinknoObjectObject comprising of {link, onClick}. link is a function whose input is {rowDatum} and outputs an href. onClick is a function that is executed when the row is clicked. Only valid with withRowLink plugin.

Column object props

PropertyRequiredTypeDefaultDescription
attributeyesStringThe key to use in the data prop to get data for that column
classNamenoString or FunctionThe class(es) to apply to a column. If this is a function, the inputs are (rowDatum, isHeader). Only valid when used with withCellClassName plugin.
displayNamenoStringThe text in the TableHeader for that column
ellipsisnoBooleanfalseEllipsify overflow text. Only valid when used with withCellEllipsis plugin.
linknoFunctionThe link destination. Only valid when used with withCellLink plugin.
onClicknoFunctionThe function to execute when the cell is clicked. The inputs to this function are (event, rowDatum). Only valid when used with withCellOnClick plugin.
renderTdChildrennoFunctionFunction which will be called to render custom cell children. Called with rowDatum as its argument. Only valid when used with withRenderTdChildren plugin.
renderThChildrennoFunctionFunction which will be called to render custom header children. Only valid when used with withRenderThChildren plugin.
sortablenoBooleanDetermines whether a column is sortable. Only valid when used with withSorting plugin.
sortBynoFunctionFunction that determines sort order. The input is the cell data. Only valid when used with withSorting plugin and if sortable is true.
tooltipnoFunctionFunction whose inputs are ({isHeader}, rowDatum) and should output an object containing {text, size, theme, showIcon}. text and size are used in the Tooltip Component. theme is a prop of the OverlayTrigger Component. showIcon determines if the info icon is shown. Only valid when used with withCellTooltip plugin.
widthnoStringCan be any valid CSS width input. Only valid when used with withCellWidth plugin.

Imports

Import React components (including CSS):

import {Table, FlexTable, SortableTable, SortableFlexTable, AdvancedTable} from 'pivotal-ui/react/table';

Import CSS only:

import 'pivotal-ui/css/tables';