14.0.0 • Published 5 months ago

@material/data-table v14.0.0

Weekly downloads
22,183
License
MIT
Repository
github
Last release
5 months ago

Data Table

Data tables display sets of data.

Design & API Documentation

Installation

npm install @material/data-table

Styles

@import "@material/data-table/mdc-data-table";

NOTE: Styles for any components you intend to include within data-table (e.g. Checkboxes, etc.) must also 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-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">
        <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">24</td>
        <td class="mdc-data-table__cell">4.0</td>
      </tr>
      <tr class="mdc-data-table__row mdc-data-table__row--selected" aria-selected="true">
        <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" 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">37</td>
        <td class="mdc-data-table__cell">4.3</td>
      </tr>
    </tbody>
  </table>
</div>

Style Customization

CSS Classes

CSS ClassDescription
mdc-data-tableMandatory. The root DOM element containing table and other supporting elements.
mdc-data-table__tableMandatory. Table element. Added to table HTML tag.
mdc-data-table__header-rowMandatory. Table header row element. Added to thead > tr HTML tag.
mdc-data-table__header-cellMandatory. Table header cell element. Added to thead > th > td HTML tag.
mdc-data-table__header-cell--checkboxOptional. Table header cell element that contains mdc-checkbox. Added to thead> th > td:first-child HTML tag.
mdc-data-table__contentMandatory. Table body element. Added to tbody HTML tag.
mdc-data-table__rowMandatory. Table row element. Added to tbody > tr HTML tag.
mdc-data-table__cellMandatory. Table cell element. Added to tbody > tr > td HTML tag.
mdc-data-table__cell--numericOptional. Table cell element that contains numeric data. Added to tbody > tr > td HTML tag.
mdc-data-table__cell--checkboxOptional. Table cell element that contains mdc-checkbox. Added to thead> th > td:first-child HTML tag.
mdc-data-table__header-row-checkboxOptional. 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-checkboxOptional. 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--selectedOptional. Modifier class added to mdc-data-table__row when table row is selected.

Sass Mixins

MixinDescription
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 constantEvent nameDescription
ROW_SELECTION_CHANGEDMDCDataTable:changedEvent emitted when row checkbox is checked or unchecked.
SELECTED_ALLMDCDataTable:selectedAllEvent emitted when header row checkbox is checked.
UNSELECTED_ALLMDCDataTable:unselectedAllEvent emitted when header row checkbox is unchecked.

MDCDataTable Properties and Methods

Method SignatureDescription
layout() => voidRegisters 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|nul>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 SignatureDescription
addClassAtRowIndex(rowIndex: number, cssClasses: string) => voidAdds a class name to row element at given row index excluding header row.
getRowCount() => numberReturns row count excluding header row.
getRowElements() => HTMLElement[]Returns array of row elements excluding header row.
getRowIdAtIndex(rowIndex: number) => string | nullReturns row id of row element at given row index based on data-row-id attribute on row element tr.
getRowIndexByChildElement(el: Element) => numberReturns index of row element that contains give child element.
getSelectedRowCount() => numberReturns selected row count.
isHeaderRowCheckboxChecked() => booleanReturns true if header row checkbox is checked.
isRowsSelectable() => booleanReturns true if table rows are selectable.
notifyRowSelectionChanged(data: MDCDataTableRowSelectionChangedEventDetail) => voidNotifies when row selection is changed.
notifySelectedAll() => voidNotifies when header row is checked.
notifyUnselectedAll() => voidNotifies when header row is unchecked.
registerHeaderRowCheckbox() => Promise<void> | voidInitializes header row checkbox. Destroys previous header row checkbox instance if any. Can return Promise only if registering checkbox is asynchronous.
registerRowCheckboxes() => Promise<void> | voidInitializes 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) => voidRemoves class name from row element at give row index.
setAttributeAtRowIndex(rowIndex: number, attr: string, value: string) => voidSets attribute to row element at given row index.
setHeaderRowCheckboxChecked(checked: boolean) => voidSets header row checkbox checked or unchecked.
setHeaderRowCheckboxIndeterminate(indeterminate: boolean) => voidSets header row checkbox to indeterminate.
setRowCheckboxCheckedAtIndex(rowIndex: number, checked: boolean) => voidSets row checkbox to checked or unchecked at given row index.

MDCDataTableFoundation

Method SignatureDescription
layout() => voidRe-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> | voidRe-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[]) => voidSets selected row ids. Overwrites previously selected rows.
getSelectedRowIds() => Array<string|null>Returns array of selected row ids.
handleHeaderRowCheckboxChange() => voidHandles header row checkbox change event.
handleRowCheckboxChange(event: Event) => voidHandles change event originated from row checkboxes.
14.0.0

2 years ago

13.0.0

3 years ago

12.0.0

3 years ago

11.0.0

3 years ago

10.0.0

3 years ago

9.0.0

3 years ago

8.0.0

3 years ago

7.0.0

4 years ago

6.0.0

4 years ago

5.1.0

4 years ago

5.0.0

4 years ago

4.0.0

4 years ago

3.2.0

5 years ago

4.0.0-canary.1

5 years ago

4.0.0-canary.0

5 years ago

3.1.1

5 years ago

4.0.0-alpha.0

5 years ago

3.1.0

5 years ago

3.1.0-alpha.0

5 years ago

3.0.0-alpha.1

5 years ago

3.0.0-alpha.0

5 years ago