grommet
docs
components

DataTable

a data driven table

Storybook
CodeSandbox
Github

Using Grommet for HPE?See DataTable examples and guidance.

Props

a11yTitle

Custom label to be used by screen readers. When provided, an aria-label will be added to the element.

string
"a user friendly label for screen readers"

alignSelf

How to align along the cross axis when contained in a Box or along the column axis when contained in a Grid.

string
"start"
"center"
"end"
"stretch"

background

Cell background.

string
"light-2"
array

If you pass an array, rows will cycle between the array values.

["white", "light-2"]
object

You can set the background per context by passing an object with keys for 'heading', 'body', and/or 'footer'.


{
  header: "dark-2",
  body: ["white", "light-2"],
  footer: { dark: "light-2", light: "dark-3" }
}

border

Cell border.

boolean
true
false
string
"horizontal"
"vertical"
"top"
"bottom"
"right"
"left"
object

You can set the border per context by passing an object with keys for 'heading', 'body', and/or 'footer'.


{
  color: "border",
  side: "horizontal",
  size: "small"
}
            

{
  header: "bottom",
  body: {
    color: "light-2",
    side: "bottom"
  },
  footer: "top"
}

columns

A description of the data.

array

The order controls the column order. 'property' indicates which property in the data objects to associate the column with. 'header' indicates what to display in the column header. 'render' allows for custom rendering of body cells. Use 'render' for custom formatting for things like currency and date or to display rich content like Meters. 'align' indicates how the cells in the column are aligned. 'aggregate' indicates how the data in the column should be aggregated. This only applies to a footer or groupBy context. 'footer' indicates what should be shown in the footer for the column. 'search' indicates whether a search filter should be made available for the column. 'primary' indicates that this property should be used as the unique identifier, which gives the cell 'row' scope for accessibility. If 'primary' is not used for any column, and 'primaryKey' isn't specified either, then the first column will be used. 'pin' indicates that this column should not scroll out of view to the left when the table is scrolled horizontally. 'plain' = true indicates that the body cells in the column will not apply pad.


[
  {
    align: "...",
    aggregate: "...",
    footer: node | { aggregate: "..." },
    header: string | node | { aggregate: "..." },
    pin: boolean,
    plain: boolean,
    primary: boolean,
    property: "string",
    render: function,
    search: boolean,
    sortable: boolean,
    size: "...",
    units: "string",
    verticalAlign: "..."
  }
]
where align could be:
"start"
"center"
"end"
where aggregate could be:
"avg"
"max"
"min"
"sum"
where size could be:
"small"
"medium"
"large"
"xlarge"
"1/2"
"1/4"
"2/4"
"3/4"
"1/3"
"2/3"
"string"
where verticalAlign could be:
"middle"
"top"
"bottom"

data

Array of data objects.

array
[{}]

disabled

When supplied, disables 'onClickRow' and 'onSelect' interaction for the indicated rows. The values in this array should match the 'primaryKey' or 'columns[].primary' keyed value for the row's data object.

array
["string"]
[number]

fill

Whether the width and/or height should fill the container.

string
"horizontal"
"vertical"
boolean
true
false

gridArea

The name of the area to place this inside a parent Grid.

string
"a parent grid area name"

groupBy

Property to group data by.

string
"location"
object

If object is specified 'property' is used to group data by, 'expand' accepts array of group keys that sets expanded groups and 'onExpand' is a function that will be called after expand button is clicked with an array of keys of expanded groups. If 'onUpdate' is being used to lazy load group items, 'expandable' can be used to specify which items in the data are group header items and 'select' and 'onSelect' can be specified in 'groupBy' to help specify the selection state of the groups and handle changes in group selection state.


{
  "property": "location",
  "expand": ["Paris", "Los Angeles"],
  "onExpand": "(key) => {...}"
}
            

{
  "property": "location",
  "expand": ["Paris", "Los Angeles"],
  "expandable": ["Paris", "Los Angeles", "Fort Collins", "San Jose"],
  "select": { "": "some", "Paris": "all", "Los Angeles": "some"}
  "onSelect": (selected, datum, groupBySelected) => {...}
}

margin

The amount of margin around the component.

string
"none"
"xxsmall"
"xsmall"
"small"
"medium"
"large"
"xlarge"
object

Can be specified to distinguish horizontal margin, vertical margin, and margin on a particular side.


{
    vertical: "...",
    horizontal: "...",
    top: "...",
    bottom: "...",
    left: "...",
    right: "..."
}

onClickRow

When supplied, this function will be called with an event object that include a 'datum' property containing the data value associated with the clicked row. You should not include interactive elements, like Anchor or Button inside table cells as that can cause confusion with overlapping interactive elements. If onSelect is being used you have the option to make the whole row clickable by passing in select to onClickRow.

function
({ datum }) => {...}
string
'select'

onMore

Use this to indicate that 'data' doesn't contain all that it could. It will be called when all of the data rows have been rendered. This might be used when the total number of items that could be retrieved is more than you'd want to load into the browser. 'onMore' allows you to lazily fetch more from the server only when needed. This cannot be combined with properties that expect all data to be present in the browser, such as columns.search, sortable, groupBy, or columns.aggregate.

function
() => {}

onSearch

When supplied, and when at least one column has 'search' enabled, this function will be called with an object with keys for property names and values which are the search text strings. This is typically employed so a back-end can be used to search through the data.

function
({ key: "search text", ... }) => {...}

onSelect

When supplied, causes checkboxes to be added to each row such that the user can indicate which rows should be selected.

function

This function will be called with an array of primary key values, suitable to be passed to the 'select' property, along with the data item that was changed. If you are storing select state via a 'useState' hook, you can do something like: ' <DataTable select={select} onSelect={setSelect} />'.

(selected, datum) => {}

onSort

When supplied, this function will be called with an object with a 'property' property that indicates which property is being sorted on and a 'direction' property that will either be 'asc' or 'desc'.

function
({ property, direction }) => {}

onUpdate

This function provides a way to lazy-load data. It is similar to `onMore` except it also allows for lazily providing expanded group data and assumes the `data` is already in sorted order. Like `onMore`, DataTable will call `onUpdate` when the user has scrolled to the end of existing data. `onUpdate` is also called when the sort changes or a group is expanded or collapsed by the user. It is passed information on the current sort settings and the maximum number of items it needs to return. If `groupBy` is specified, `data` should include an item for each group also. This item should have its own unique value in the property specified as the `primaryKey` and this unique key value should be listed in `groupBy.expandable` so the DataTable can tell it is a group header. `onUpdate` will be passed an array of group keys for groups that are currently expanded so it can decide whether to include items for a group's members. If the table also has `select` or `onSelect` specified, `groupBy` should also include an `onSelect` callback and a separate `select` to define the overall selection state of the groups. Since DataTable may not have all the items, it is up to the onSelect callbacks and onUpdate to determine if groups are fully or partially selected and set that in `groupBy.select`.

function
({ expanded, sort, show, count }) => {}

pad

Cell padding.

string

T-shirt sizing based off the theme or a specific size in px, em, etc.

"xxsmall"
"xsmall"
"small"
"medium"
"large"
"xlarge"
"any CSS size"
object

An object can be specified to distinguish horizontal padding, vertical padding, and padding on a particular side.

You can set the padding per context by passing an object with keys for 'heading', 'body', and/or 'footer'.


{
  vertical: "...",
  horizontal: "...",
  top: "...",
  bottom: "...",
  left: "...",
  right: "...",
  start: "...",
  end: "..."
}
        

{
  header: "...",
  body: "...",
  footer: "..."
}

paginate

Whether to paginate the data.

boolean
true
false
object

If providing an object, any Box props or Pagination props are valid and will be used to style the underlying pagination component.

{}

pin

Whether the header and/or footer should be pinned when not all rows are visible. A value of true pins both header and footer.

boolean
true
false
string
"header"
"footer"

placeholder

A text message or any content to place over the table body. For example, to say "loading ..." when waiting for data to arrive.

string
"loading..."
node
<Box>...</Box>

primaryKey

When supplied, indicates the property for a data object to use to get a unique identifier. See also the 'columns.primary' description. Use this property when the columns approach will not work for your data set. Setting primaryKey to false indicates there should be no unique identifier, avoid this as it's less accessible.

boolean
true
false
string
"property"

replace

Whether to replace previously rendered items with a generic spacing element when they have scrolled out of view. This is more performant but means that in-page searching will not find elements that have been replaced.

boolean
true
false

resizeable

Whether to allow the user to resize column widths.

boolean
true
false

rowDetails

When supplied, this function will be called with row data. Function can return a React Element which will be rendered on expanding the row.

function
() => {}

rowProps

Row specific background, border, and pad, keyed by primary key value. The background, border, and pad accept the same values as the same named properties on DataTable.

object
{ "primary-key-value": { background: ..., border: ..., pad: ... }}

select

When supplied, causes checkboxes to be added to each row to indicate which rows are selected. The values in this array should match the 'primaryKey' or 'columns[].primary' keyed value for the row's data object. If 'onSelect' is provided, the CheckBoxes are enabled and this function can be used to track select changes.

array
["string"]
[number]

show

The item or page to show.

number

If provided as a number, the index of an item to show.

10
object

If using paginate and provided as an object in the format of the default page to show.

{ page: 2 }

size

The height of the table body. If set, the table body will have a fixed height and the rows will be scrollable within it. In order to preserve header and footer cell alignment, all cells will have the same width. This cannot be used in combination with 'resizeable'.

string
"small"
"medium"
"large"
"xlarge"
"string"

sort

Which property to sort on and which direction to sort. When 'external' is true, it indicates that the caller will take care of sorting the 'data' via 'onSort'. Otherwise, the existing data will be sorted within DataTable.

object

{
  direction: "asc" | "desc",
  external: boolean,
  property: "string"
}

sortable

Whether to allow the user to sort columns.

boolean
true
false

step

How many items to render at a time.

number
50

verticalAlign

How to vertically align items.

string
"bottom"
"middle"
"top"
object

{
  header: "string",
  body: "string",
  footer: "string"
}

React/DOM Properties

At its core, the DataTable component is a regular <table> element. Thus, both DOM and React properties, methods, and events are accessible. To read up on all of the possible DOM attributes and types available for table elements, check out this MDN Web Documents page. To learn more about DOM events and methods, you can read more on the MDN Web Events documentation page.

Also, feel free to read about the types of React events available, or see how DOM attributes change in React. Working in tandem with Styled Components, you also have access to the as property.

Theme

global.hover.background

The background style when hovering over an interactive row.

string

A hex, name, or rgb value.

"active"
object
{ color: 'active', opacity: 'medium' }

global.hover.color

The text color when hovering over an interactive row.

string

A hex, name, or rgb value.

"black"
object

An object with a color for dark and light modes.

{ dark: 'white', light: 'black' }

dataTable.body.extend

Any additional style for an DataTable Body.

string

Any CSS.

css`color: 'blue'`
function
(props) => {}

dataTable.container

When using paginate, any valid Box props for the container surrounding the DataTable and Pagination components.

object
{ gap: 'small' }

dataTable.container.extend

Any additional style for the container surrounding the DataTable and Pagination components.

string

Any CSS.

css`color: 'blue'`
function
(props) => {}

dataTable.groupHeader.background

The background color of the group header.

string

A hex, name, or rgb value.

"light-2"
object

An object with a color for dark and light modes.

{ dark: 'dark-2', light: 'light-2' }

dataTable.groupHeader.border.side

The border side rendered for the group header.

string
"bottom"

dataTable.groupHeader.border.size

The border size of the group header border.

string
"xsmall"

dataTable.groupHeader.fill

Whether the height should fill the group header.

string
"vertical"

dataTable.groupHeader.pad

The pad used for the group header.

string
"small"
object
{ horizontal: "small", vertical: "xsmall" }

dataTable.header

Styles for the header.

object

{
  gap: "small",
  units: {
    color: "text-xweak",
    margin: { left: "xsmall" }
  }
}

dataTable.header.background

Any valid Box background value.

string
"background"
object
{ dark: string, light: string }

{
  color: { dark: string, light: string } | string,
  dark: bool,
  image: string,
  position: string,
  opacity: bool | string,
  repeat: no-repeat | repeat,
  size: cover | contain | string
}

dataTable.header.border

Any valid Box border value.

string
"bottom"
object

{
  color: string | { dark: string, light: string },
  size: "medium",
  style: "dashed",
  side: "all"
}

dataTable.header.color

The label and icon color in a header cell.

string

A hex, name, or rgb value.

"brand"
object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

dataTable.header.extend

Any additional styles for header cells.

string

Any CSS.

css`color: 'blue'`
function
(props) => {}

dataTable.header.font.weight

The font weight for text in header cells.

string
"bold"

dataTable.header.font.size

The font size for text in header cells.

string
"24px"

dataTable.header.gap

The gap between elements within the header cell.

string
"small"

dataTable.header.hover.background

The hover background color of the header cell contents, if clickable. Any valid Box background options apply.

string
"background"
object
{ dark: string, light: string }

{
  color: { dark: string, light: string } | string,
  dark: bool,
  image: string,
  position: string,
  opacity: bool | string,
  repeat: no-repeat | repeat,
  size: cover | contain | string
}

dataTable.header.pad

The pad around the contents of the header cell.

string
"small"
object
{ horizontal: "small", vertical: "xsmall" }

dataTable.header.units

Any Text component properties for styling the header's units text.

object

{
  color: "text-xweak",
  margin: { left: "xsmall" }
}

dataTable.resize.hover.color

The color of the resizer when hovered over.

string

A hex, name, or rgb value.

"brand"
object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

dataTable.resize.hover.side

The side of the resizer when hovered over. If color or size are defined, this will default to 'end' which is the recommended value.

string
"end"

dataTable.resize.hover.size

The size of the resizer when hovered over. Size values correspond with those accepted by Box border.

string
"2px"

dataTable.icons.ascending

The ascending icon.

element
<FormDown />

dataTable.icons.contract

The contract icon.

element
<FormUp />

dataTable.icons.descending

The descending icon.

element
<FormUp />

dataTable.icons.expand

The expand icon.

element
<FormDown />

dataTable.icons.sortable

The icon indicating a column can be sorted.

element
<Icon />

dataTable.pinned.body.background

Any valid Box background options apply.

string
"background"
object
{ dark: string, light: string }

{
  color: { dark: string, light: string } | string,
  dark: bool,
  image: string,
  position: string,
  opacity: bool | string,
  repeat: no-repeat | repeat,
  size: cover | contain | string
}

dataTable.pinned.body.extend

Any additional styles for pinned body cells.

string

Any CSS.

css`color: 'blue'`
function
(props) => {}

dataTable.pinned.header.background

Any valid Box background options apply.

string
"background"
object
{ dark: string, light: string }

{
  color: { dark: string, light: string } | string,
  dark: bool,
  image: string,
  position: string,
  opacity: bool | string,
  repeat: no-repeat | repeat,
  size: cover | contain | string
}

dataTable.pinned.header.extend

Any additional styles for pinned header cells.

string

Any CSS.

css`color: 'blue'`
function
(props) => {}

dataTable.pinned.footer.background

Any valid Box background options apply.

string
"background"
object
{ dark: string, light: string }

{
  color: { dark: string, light: string } | string,
  dark: bool,
  image: string,
  position: string,
  opacity: bool | string,
  repeat: no-repeat | repeat,
  size: cover | contain | string
}

dataTable.pinned.footer.extend

Any additional styles for pinned footer cells.

string

Any CSS.

css`color: 'blue'`
function
(props) => {}

dataTable.primary.weight

The font weight for primary cells.

string
"bold"

dataTable.resize.border.color

The border color for resize.

string

A hex, name, or rgb value.

"border"
object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

dataTable.resize.border.side

The border side used for resize.

string
"right"

table.row.hover.background

The background color when hovering over an interactive row.

string

A hex, name, or rgb value.

"brand"
object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

table.row.hover.color

The text color when hovering over an interactive row.

string

A hex, name, or rgb value.

"brand"
object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }