Data Table

Material Design 3 data table for sortable, filterable, paginated, and selectable tabular data. Not intended for hierarchical tree data or dense spreadsheet editing workflows.

Basic Usage

Render a simple table with data and column definitions. This provides a consistent shell for sorting, filtering, and pagination in data-heavy views. 

<ds-data-table
  data='[{"name":"Alice","age":30},{"name":"Bob","age":25}]'
  columns='[{"key":"name","label":"Name"},{"key":"age","label":"Age"}]'>
</ds-data-table>

Initial Value

Set initial data and columns from JavaScript for richer configurations. 

const table = document.querySelector('#initial-table');
table.data = [{ id: 1, name: 'Alice', age: 30 }];
table.columns = [
  { key: 'name', label: 'Name' },
  { key: 'age', label: 'Age' }
];

Variants/Formats

Use configuration flags and column formatting for different display needs.

Sortable and Filterable

<ds-data-table sortable filterable></ds-data-table>

Custom Column Formatting

const columns = [
  { key: 'name', label: 'Name' },
  {
    key: 'salary',
    label: 'Salary',
    format: (value) => `$${value.toLocaleString()}`
  },
  {
    key: 'active',
    label: 'Active',
    format: (value) => (value ? 'Yes' : 'No')
  }
];

Density Options

<ds-data-table density="default"></ds-data-table>
<ds-data-table density="comfortable"></ds-data-table>
<ds-data-table density="compact"></ds-data-table>

States

Common state combinations for real application tables.

No Pagination

No Filtering

Selectable Rows

<ds-data-table paginated="false"></ds-data-table>
<ds-data-table filterable="false"></ds-data-table>
<ds-data-table selectable></ds-data-table>

Interactive Example

Interact with the table and inspect emitted events.

Waiting for events...
const table = document.querySelector('#interactive-table');

['ds-data-table:sort', 'ds-data-table:filter', 'ds-data-table:page', 'ds-data-table:select']
  .forEach((eventName) => {
    table.addEventListener(eventName, (event) => {
      console.log(eventName, event.detail);
    });
  });

API Reference

Attributes

Attribute Type Default Description
data string (JSON) [] JSON array of row objects
columns string (JSON) [] JSON array of column definitions
sortable boolean true Enable header sorting
filterable boolean true Enable filter input
paginated boolean true Enable pagination footer
page-size number 10 Rows per page
selectable boolean false Enable row selection checkboxes
density string default default, comfortable, or compact

Properties

Property Type Description
data Array Gets or sets table row data
columns Array Gets or sets table column definitions
selectedRows Array Returns selected row indexes

Events

Event Detail Description
ds-data-table:sort { column, direction } Emitted after sort changes
ds-data-table:filter { value } Emitted after filter value changes
ds-data-table:page { page, pageSize } Emitted after page navigation
ds-data-table:select { selectedRows, indices } Emitted after row selection changes

CSS Parts

Part Description
container Outer container wrapping toolbar, table, and footer
toolbar Top toolbar containing filter controls
table Table element
header Table header section
body Table body section
footer Pagination footer

Methods

Method Description
getTotalPages() Returns total pages based on filtered data and page size
getPageData() Returns the data slice for the current page

Accessibility

Keyboard Interaction

Key Context Expected Result
Tab / Shift+Tab Toolbar, table, pagination Moves focus across filter, header controls, rows, and paging buttons
Enter / Space Sort headers / row selection controls Triggers sort direction changes or row selection

Semantics

  • Uses semantic table markup and role="table".
  • Filter and pagination controls include descriptive aria-label values.
  • Interactive controls maintain visible focus indicators.

Usage Guidelines

  • When to use: Use for structured, comparable datasets where users need sorting, filtering, and page-level navigation.
  • When not to use: Avoid for card-first mobile layouts, unstructured content feeds, or deeply nested hierarchies.
  • Composition: Combine filtering and sorting for large datasets, use compact density only where scan speed is prioritized, and enable selection only with bulk actions.
  • Common mistakes: Overloading columns hurts readability. Define formatting logic in JavaScript for consistent value rendering.