Skip to content
Paste
UX Platform
Change the site theme
information:

Data Grid

Design assets pending
Peer review pending

A data grid is an interactive table used for working with a large collection of data in a scannable way.


First NameLast NameCountryEmailPhone
LottieHintzRepublic of KoreaJohn.Zulauf@gmail.com1-652-451-4330
PaigeKshlerinBritish Indian Ocean Territory (Chagos Archipelago)Natalie.Klein@yahoo.com668.667.3238 x27714
KadinWillHaitiOra_Bartoletti@yahoo.com446.666.1937 x759
TroyMcDermottQatarRichmond34@hotmail.com(209) 774-9227 x5109
DevynWeimannCongoMatilde86@gmail.com652-441-1766 x377
TristonDickinsonFrench Southern TerritoriesViolette.Kihn97@yahoo.com939.571.3994
MaeveWestNorwayMittie80@yahoo.com395.983.4598 x8023
TraceyFarrellMacaoBarrett72@yahoo.com1-805-781-6325
JovannyMantePitcairn IslandsFausto_Vandervort15@gmail.com(629) 375-5743 x726
FritzBashirianFranceMagali.Harber@hotmail.com1-229-278-7567

Guidelines#

About Data Grid#

The Data Grid is an enhanced Table component. It can be used to improve the way users scan and interact with tabular data. It can be used alongside other components in Paste to provide the following functionality:

  • Full keyboard navigation
  • Responsive horizontal scrolling
  • Column sorting
  • Editable cells
  • Selectable rows
  • Pagination

Accessibility#

Semantics#

  • The DataGrid component uses HTML table elements rather than div elements. This provides better screen reader support.
  • The DataGrid table element has role="grid" applied.
  • The DataGrid table element has an aria-label provided.
  • The DataGridRow tr element has role="row" applied.
  • The DataGridRow tr element has an aria-selected provided.
  • Column headers with sorting list the direction with the aria-sort attribute.

Keyboard navigation#

The data grid can be in two navigational modes: Actionable and Navigational. Each has different requirements listed below:

  • The data grid has one tab stop. This means if you press the [Tab] key to enter the data grid, the next [Tab] key press will take you to the first element outside the data grid.
  • Data cells can be focused using standard navigation keys, including directional arrows, [Home], [End], [Control+Home], [Control+End], [Page up], and [Page down].
  • Tabbing out of the table and back into the table will restore focus to the last selected data cell.
  • Pressing the [Enter] key will swap the user into the Actionable mode. If there‚Äôs a focusable child element in the current cell, it will gain focus.
Actionable:#
  • Data grid cells lose the ability to focus. However, focusable elements inside each cell regain their tabindex.
  • The user can [Tab] through all the focusable elements in the table.
  • Pressing the [Escape] key returns the user to Navigational mode, and moves the focus to the closest parent cell.
  • When interacting with a component in a cell that also uses the [Escape] key, the user will need to press the [Escape] key twice to return to Navigational mode.

Examples#

Data grid with custom cell content#

This example shows the composition of Paste components like Input and Select in the cells. Notice how the tabIndex is correctly managed without any additional code.

Data grid with selectable rows#

Row selection is achieved with the CheckboxGroup and Checkbox components and the selected prop on DataGridRow.

Data grid with sortable columns#

This package exports a DataGridHeaderSort component which render the UI for a sort button in the DataGridHeader. Please be mindful to correctly set the aria-sort attribute on the DataGridHeader component.

Data grid with pagination#

It is not ideal to display more than a few rows at a time (consider 10 as a default), so the Pagination component is used to handle multiple pages of information.

Data grid in a loading state#

Rather than using a Spinner component, you can use the Skeleton Loader in the cells to create a more pleasant loading experience.

Kitchen sink#

This example combines all the separate features displayed previously into one example. It shows how all the features work together harmoniously through composition.

Composition Notes#

The Data Grid component was designed to be accessible and composable. This means it can adapt to any of your product and development needs while providing an inclusive experience for all of your users.

This package provides the following component exports, which correspond closely to HTML table element naming:

  • DataGrid
  • DataGridHead
  • DataGridRow
  • DataGridHeader
  • DataGridHeaderSort
  • DataGridBody
  • DataGridCell
  • DataGridFoot

You are free to put any Paste component in the Data Grid cells and it should just work. Keep in mind that anything that dynamically updates an element's tabIndex value may fail to work correctly.

When to use a Data Grid#

Information icon

Don't forget about the Table component

If the data is static and doesn't need sorting, prefer to use a Table component which is more lightweight.

Do

Use data grid for interactive, tabular data

Don't

Don't use data grid for static data


Usage Guide#

API#

Installation#

yarn add @twilio-paste/core

Usage#

import {
DataGrid,
DataGridHead,
DataGridRow,
DataGridHeader,
DataGridBody,
DataGridCell,
DataGridFoot,
} from '@twilio-paste/core/data-grid';
const Component = () => (
<DataGrid aria-label="User information table" striped>
<DataGridHead>
<DataGridRow>
<DataGridHeader>First Name</DataGridHeader>
<DataGridHeader>Last Name</DataGridHeader>
<DataGridHeader>Country</DataGridHeader>
<DataGridHeader>Email</DataGridHeader>
<DataGridHeader>Phone</DataGridHeader>
</DataGridRow>
</DataGridHead>
<DataGridBody>
<DataGridRow>
<DataGridCell>Devyn</DataGridCell>
<DataGridCell>Weimann</DataGridCell>
<DataGridCell>Congo</DataGridCell>
<DataGridCell>Matilde86@gmail.com</DataGridCell>
<DataGridCell>652-441-1766 x377</DataGridCell>
</DataGridRow>
<DataGridRow>
<DataGridCell>Fritz</DataGridCell>
<DataGridCell>Bashirian</DataGridCell>
<DataGridCell>France</DataGridCell>
<DataGridCell>Magali.Harber@hotmail.com</DataGridCell>
<DataGridCell>1-229-278-7567</DataGridCell>
</DataGridRow>
<DataGridRow>
<DataGridCell>Jovanny</DataGridCell>
<DataGridCell>Mante</DataGridCell>
<DataGridCell>Pitcairn Islands</DataGridCell>
<DataGridCell>Fausto_Vandervort15@gmail.com</DataGridCell>
<DataGridCell>(629) 375-5743 x726</DataGridCell>
</DataGridRow>
</DataGridBody>
<DataGridFoot>
<DataGridRow>
<DataGridCell>Devyn</DataGridCell>
<DataGridCell>Weimann</DataGridCell>
<DataGridCell>Congo</DataGridCell>
<DataGridCell>Matilde86@gmail.com</DataGridCell>
<DataGridCell>652-441-1766 x377</DataGridCell>
</DataGridRow>
</DataGridFoot>
</DataGrid>
);

DataGrid Props#

PropTypeDescriptionDefault
aria-labelstringDefines a string value that labels the current element.null
striped?booleanToggles row zebra stripingfalse
element?stringOverride for customization element nameDATA_GRID
children?ReactNodenull

DataGridHead Props#

PropTypeDescriptionDefault
element?stringOverride for customization element nameDATA_GRID_HEAD
children?ReactNodenull

DataGridBody Props#

PropTypeDescriptionDefault
element?stringOverride for customization element nameDATA_GRID_BODY
children?ReactNodenull

DataGridFoot Props#

PropTypeDescriptionDefault
element?stringOverride for customization element nameDATA_GRID_FOOT
children?ReactNodenull

DataGridHeader Props#

PropTypeDescriptionDefault
textAlign?stringCSS text align for this cellleft
width?stringAllows setting column width programmaticallynull
element?stringOverride for customization element nameDATA_GRID_HEADER
children?ReactNodenull

DataGridHeaderSort Props#

PropTypeDescriptionDefault
direction"ascending", "descending", "none"Sort direction matching aria specnull
onClick?() => {}Callback when the sort button is pressed. Used to handle sorting.null
element?stringOverride for customization element nameDATA_GRID_HEADER_SORT

DataGridRow Props#

PropTypeDescriptionDefault
selected?booleanVisally displays a row highlight indicating selection and sets aria-selectedfalse
element?stringOverride for customization element nameDATA_GRID_ROW
children?ReactNodenull

DataGridCell Props#

PropTypeDescriptionDefault
as?"th", "td"Cells can either be th or td, so rows can have headers.td
textAlign?stringCSS text align for this cellleft
element?stringOverride for customization element nameDATA_GRID_CELL
children?ReactNodenull

Black lives matter.