Material Design

Data Table

Data tables display information in a grid-like format of rows and columns. They organize information in a way that’s easy to scan, so that users can look for patterns and insights.

Design & API Documentation

Installation

npm install @material/data-table

Styles

@import "@material/checkbox/mdc-checkbox"; // Required only for data table with row selection.
@import "@material/data-table/mdc-data-table";

NOTE: Styles for any components you intend to include within data-table (e.g. Checkboxes, Buttons etc.) must be imported.

JavaScript Instantiation

import {MDCDataTable} from '@material/data-table';
const dataTable = new MDCDataTable(document.querySelector('.mdc-data-table'));

See Importing the JS component for more information on how to import JavaScript.

Instantiating MDCDataTable component is only required to add interactions for example, row selection.

MDC Data Table component auto instantiates MDCCheckbox for header row checkbox and all row checkboxes. Make sure to set required class names to instantiate checkbox component. We suggest to use layout API when rows are added or removed from data table to register new checkbox components.

Basic Usage

HTML Structure

<div class="mdc-data-table">
  <table class="mdc-data-table__table" aria-label="Dessert calories">
    <thead>
      <tr class="mdc-data-table__header-row">
        <th class="mdc-data-table__header-cell" role="columnheader" scope="col">Dessert</th>
        <th class="mdc-data-table__header-cell" role="columnheader" scope="col">Carbs (g)</th>
        <th class="mdc-data-table__header-cell" role="columnheader" scope="col">Protein (g)</th>
        <th class="mdc-data-table__header-cell" role="columnheader" scope="col">Comments</th>
      </tr>
    </thead>
    <tbody class="mdc-data-table__content">
      <tr class="mdc-data-table__row">
        <td class="mdc-data-table__cell">Frozen yogurt</td>
        <td class="mdc-data-table__cell mdc-data-table__cell--numeric">24</td>
        <td class="mdc-data-table__cell mdc-data-table__cell--numeric">4.0</td>
        <td class="mdc-data-table__cell">Super tasty</td>
      </tr>
      <tr class="mdc-data-table__row">
        <td class="mdc-data-table__cell">Ice cream sandwich</td>
        <td class="mdc-data-table__cell mdc-data-table__cell--numeric">37</td>
        <td class="mdc-data-table__cell mdc-data-table__cell--numeric">4.3</td>
        <td class="mdc-data-table__cell">I like ice cream more</td>
      </tr>
      <tr class="mdc-data-table__row">
        <td class="mdc-data-table__cell">Eclair</td>
        <td class="mdc-data-table__cell mdc-data-table__cell--numeric">24</td>
        <td class="mdc-data-table__cell mdc-data-table__cell--numeric">6.0</td>
        <td class="mdc-data-table__cell">New filing flavor</td>
      </tr>
    </tbody>
  </table>
</div>

Variants

Data table with row selection

<div class="mdc-data-table">
  <table class="mdc-data-table__table" aria-label="Dessert calories">
    <thead>
      <tr class="mdc-data-table__header-row">
        <th class="mdc-data-table__header-cell mdc-data-table__header-cell--checkbox" role="columnheader" scope="col">
          <div class="mdc-checkbox mdc-checkbox--selected mdc-data-table__header-row-checkbox">
            <input type="checkbox" class="mdc-checkbox__native-control" aria-label="Toggle all rows" />
            <div class="mdc-checkbox__background">
              <svg class="mdc-checkbox__checkmark" viewbox="0 0 24 24">
                <path class="mdc-checkbox__checkmark-path" fill="none" d="M1.73,12.91 8.1,19.28 22.79,4.59" />
              </svg>
              <div class="mdc-checkbox__mixedmark"></div>
            </div>
          </div>
        </th>
        <th class="mdc-data-table__header-cell" role="columnheader" scope="col">Dessert</th>
        <th class="mdc-data-table__header-cell" role="columnheader" scope="col">Carbs (g)</th>
        <th class="mdc-data-table__header-cell" role="columnheader" scope="col">Protein (g)</th>
      </tr>
    </thead>
    <tbody class="mdc-data-table__content">
      <tr class="mdc-data-table__row" data-row-id="u0">
        <td class="mdc-data-table__cell mdc-data-table__cell--checkbox">
          <div class="mdc-checkbox mdc-data-table__row-checkbox">
            <input type="checkbox" class="mdc-checkbox__native-control" aria-labelledby="r0" />
            <div class="mdc-checkbox__background">
              <svg class="mdc-checkbox__checkmark" viewbox="0 0 24 24">
                <path class="mdc-checkbox__checkmark-path" fill="none" d="M1.73,12.91 8.1,19.28 22.79,4.59" />
              </svg>
              <div class="mdc-checkbox__mixedmark"></div>
            </div>
          </div>
        </td>
        <td class="mdc-data-table__cell" id="r0">Frozen yogurt</td>
        <td class="mdc-data-table__cell mdc-data-table__cell--numeric">24</td>
        <td class="mdc-data-table__cell mdc-data-table__cell--numeric">4.0</td>
      </tr>
      <tr class="mdc-data-table__row mdc-data-table__row--selected" aria-selected="true" data-row-id="u1">
        <td class="mdc-data-table__cell mdc-data-table__cell--checkbox">
          <div class="mdc-checkbox mdc-checkbox--selected mdc-data-table__row-checkbox">
            <input type="checkbox" class="mdc-checkbox__native-control" checked aria-labelledby="r1" />
            <div class="mdc-checkbox__background">
              <svg class="mdc-checkbox__checkmark" viewbox="0 0 24 24">
                <path class="mdc-checkbox__checkmark-path" fill="none" d="M1.73,12.91 8.1,19.28 22.79,4.59" />
              </svg>
              <div class="mdc-checkbox__mixedmark"></div>
            </div>
          </div>
        </td>
        <td class="mdc-data-table__cell" id="r1">Ice cream sandwich</td>
        <td class="mdc-data-table__cell mdc-data-table__cell--numeric">37</td>
        <td class="mdc-data-table__cell mdc-data-table__cell--numeric">4.3</td>
      </tr>
    </tbody>
  </table>
</div>

Style Customization

CSS Classes

CSS Class Description
mdc-data-table Mandatory. The root DOM element containing table and other supporting elements.
mdc-data-table__table Mandatory. Table element. Added to table HTML tag.
mdc-data-table__header-row Mandatory. Table header row element. Added to thead > tr HTML tag.
mdc-data-table__header-cell Mandatory. Table header cell element. Added to thead > th > td HTML tag.
mdc-data-table__header-cell--checkbox Optional. Table header cell element that contains mdc-checkbox. Added to thead> th > td:first-child HTML tag.
mdc-data-table__content Mandatory. Table body element. Added to tbody HTML tag.
mdc-data-table__row Mandatory. Table row element. Added to tbody > tr HTML tag.
mdc-data-table__cell Mandatory. Table cell element. Added to tbody > tr > td HTML tag.
mdc-data-table__cell--numeric Optional. Table cell element that contains numeric data. Added to tbody > tr > td HTML tag.
mdc-data-table__cell--checkbox Optional. Table cell element that contains mdc-checkbox. Added to thead> th > td:first-child HTML tag.
mdc-data-table__header-row-checkbox Optional. Checkbox element rendered inside table header row element. Add this class name to mdc-checkbox element to override styles required for data-table.
mdc-data-table__row-checkbox Optional. Checkbox element rendered inside table row element. Add this class name to mdc-checkbox element to override styles required for data-table.
mdc-data-table__row--selected Optional. Modifier class added to mdc-data-table__row when table row is selected.

Sass Mixins

Mixin Description
mdc-data-table-fill-color($color) Sets the background color of data-table surface.
mdc-data-table-row-fill-color($color) Sets the background color of table row container.
mdc-data-table-header-row-fill-color($color) Sets the background color of table header row container.
mdc-data-table-selected-row-fill-color($color) Sets the background color of selected row container.
mdc-data-table-checked-icon-color($color) Sets the checked icon color.
mdc-data-table-divider-color($color) Sets the table rows divider color.
mdc-data-table-divider-size($size) Sets the table rows divider size.
mdc-data-table-row-hover-fill-color($color) Sets the background color of table row on hover.
mdc-data-table-header-row-text-color($color) Sets the header row text color.
mdc-data-table-row-text-color($color) Sets the row text color.
mdc-data-table-shape-radius($radius) Sets the rounded shape with given radius size. $radius can be single radius or list radius values up to 4 list size.
mdc-data-table-stroke-size($size) Sets the border size of data-table.
mdc-data-table-stroke-color($color) Sets the border color of data-table.
mdc-data-table-header-row-height($height) Sets the header row height.
mdc-data-table-row-height($height) Sets row height.
mdc-data-table-cell-padding($leading-padding, $trailing-padding) Sets leading & trailing padding for all cells.
mdc-data-table-column-widths($width-list) Sets the custom widths for each table column.

Accessibility

Please refer WAI-ARIA Authoring Practices for table for ARIA recommended role, states & properties required for table element.

Events

Please use MDCDataTable’s constants file to access these event constants.

const {events} from '@material/data-table/constants';
// `events.ROW_SELECTION_CHANGED` to access event constant.
Event constant Event name Description
ROW_SELECTION_CHANGED MDCDataTable:changed Event emitted when row checkbox is checked or unchecked.
SELECTED_ALL MDCDataTable:selectedAll Event emitted when header row checkbox is checked.
UNSELECTED_ALL MDCDataTable:unselectedAll Event emitted when header row checkbox is unchecked.

MDCDataTable Properties and Methods

Method Signature Description
layout() => void Registers new row checkboxes, header row checkbox and updates the state of header row checkbox. Use this when rows are added / removed from data table.
getRows() => HTMLElement[] Returns array of row elements.
getSelectedRowIds() => Array<string \| null> Returns array of selected row ids.
setSelectedRowIds(rowIds: string[]) Sets selected row ids. Overwrites previously selected rows.

Usage within Web Frameworks

If you are using a JavaScript framework, such as React or Angular, you can create a Data Table for your framework. Depending on your needs, you can use the Simple Approach: Wrapping MDC Web Vanilla Components, or the Advanced Approach: Using Foundations and Adapters. Please follow the instructions here.

MDCDataTableAdapter

Method Signature Description
addClassAtRowIndex(rowIndex: number, cssClasses: string) => void Adds a class name to row element at given row index excluding header row.
getRowCount() => number Returns row count excluding header row.
getRowElements() => HTMLElement[] Returns array of row elements excluding header row.
getRowIdAtIndex(rowIndex: number) => string \| null Returns row id of row element at given row index based on data-row-id attribute on row element tr.
getRowIndexByChildElement(el: Element) => number Returns index of row element that contains give child element.
getSelectedRowCount() => number Returns selected row count.
isCheckboxAtRowIndexChecked(rowIndex: number) => boolean; Returns True if row checkbox at given row index is checked.
isHeaderRowCheckboxChecked() => boolean Returns true if header row checkbox is checked.
isRowsSelectable() => boolean Returns true if table rows are selectable.
notifyRowSelectionChanged(data: MDCDataTableRowSelectionChangedEventDetail) => void Notifies when row selection is changed.
notifySelectedAll() => void Notifies when header row is checked.
notifyUnselectedAll() => void Notifies when header row is unchecked.
registerHeaderRowCheckbox() => Promise<void> \| void Initializes header row checkbox. Destroys previous header row checkbox instance if any. Can return Promise only if registering checkbox is asynchronous.
registerRowCheckboxes() => Promise<void> \| void Initializes all row checkboxes. Destroys all previous row checkbox instances if any. This is usually called when row checkboxes are added or removed from table. Can return Promise only if registering checkbox is asynchronous.
removeClassAtRowIndex(rowIndex: number, cssClasses: string) => void Removes class name from row element at give row index.
setAttributeAtRowIndex(rowIndex: number, attr: string, value: string) => void Sets attribute to row element at given row index.
setHeaderRowCheckboxChecked(checked: boolean) => void Sets header row checkbox checked or unchecked.
setHeaderRowCheckboxIndeterminate(indeterminate: boolean) => void Sets header row checkbox to indeterminate.
setRowCheckboxCheckedAtIndex(rowIndex: number, checked: boolean) => void Sets row checkbox to checked or unchecked at given row index.

MDCDataTableFoundation

Method Signature Description
layout() => void Re-initializes header row checkbox and row checkboxes when selectable rows are added or removed from table. Use this if registering checkbox is synchronous.
layoutAsync() => Promise<void> \| void Re-initializes header row checkbox and row checkboxes when selectable rows are added or removed from table. Use this only if registerRowCheckboxes and registerHeaderRowCheckboxe are asynchronous.
getRows() => HTMLElement[] Returns array of row elements.
setSelectedRowIds(rowIds: string[]) => void Sets selected row ids. Overwrites previously selected rows.
getSelectedRowIds() => Array<string \| null> Returns array of selected row ids.
handleHeaderRowCheckboxChange() => void Handles header row checkbox change event.
handleRowCheckboxChange(event: Event) => void Handles change event originated from row checkboxes.