Design

​

Anatomy

The DataTable consists of several key structural elements:

1. Header row – Contains column labels with optional sort indicators
2. Header cell – Individual column header with label and optional sorting control
3. Body rows – Data rows containing cell content
4. Body cells – Individual data cells with formatted content
5. Selection column – Optional checkbox column for row selection
6. Expansion column – Optional expand/collapse control for sub-rows or sub-components. Shifts with content
7. Footer row – Optional summary or aggregate data
8. Pagination controls – Navigation for paginated data sets
9. Pinned/locked column – Column that stays in place as user scrolls

​

Options

​

Sortable Columns

Enable sorting on columns to let users click the header and sort data in ascending or descending order. A sort indicator shows the current sort direction. Clicking a sortable column header cycles through: ascending → descending → unsorted. Only one column can be sorted at a time.

​

Resizable Columns

Columns can optionally be made resizable. When this is turned on, users can resize columns by dragging the column border. Configure minimum and maximum widths to constrain resizing.

​

Pinned Columns

When tables have many columns requiring horizontal scroll, pin essential columns (like row identifiers or action columns). Pinned columns stay in place during horizontal scrolling, keeping important data visible.

​

Grouped Columns

Group columns under a parent header to create a two-level header structure. Use this to organize related data. Please note that grouped columns cannot be pinned.

​

Pagination

When enabled, pagination controls display at the bottom of the table showing:

• Current page range (e.g., “1-25 of 100”)
• Navigation buttons for first, previous, next, and last page

​

Cell Types

The DataTable provides the following cell types:

Image	Type of Cell	Alignment
	Actions cell	Left
	Cell with chip/chips	Left
	Cell with currency	Right
	Custom cell	Left
	Cell with date	Right
	Cell with date-time	Right
	Empty cell	Left
	Cell with number	Right
	Cell with percentage	Right
	Cell with text	Left
	Cell with time	Right

​

Behaviors

​

Editing

Columns can be made editable, which enables edit on hover per cell.

​

Row Selection

When selection is enabled, a checkbox column appears as the first column. Users can select individual rows or use the header checkbox to select all visible rows.

​

Row Expansion

Expand rows to show additional content in two ways:

1. Sub-rows: Nested rows with the same column structure as the parent
2. Sub-components: Custom content rendered below the parent row

​

Visual States

​

Header Cell States

​

Body Cell States

​

Keyboard Interactions

Users can navigate the DataTable using the following keyboard controls:

​

Accessibility

The DataTable implements accessibility features to ensure all users can interact with tabular data effectively:

• Proper semantic HTML table structure (table, thead, tbody, tr, th, td)
• ARIA attributes for row and column counts
• Sortable headers announce sort state to screen readers
• Selection checkboxes include descriptive labels
• Expand/collapse buttons include aria-expanded and aria-controls
• Loading states announced via aria-live regions
• Focus management maintains logical keyboard navigation
• Editable cells announce their editable state

​

Usage Guidelines

​

When to Use

Use the DataTable when displaying structured tabular data that requires any of the following:

• Sorting – Users need to reorder data by different columns
• Pagination – Data sets are too large to display all at once
• Row selection – Users need to select rows for batch operations
• Row expansion – Additional details need to be shown for individual rows
• Inline editing – Users need to modify cell values directly
• Column pinning – Key columns should remain visible during horizontal scroll

​

When Not to Use

Avoid using DataTable in these scenarios:

• Simple lists – Use ListView or Listbox for simple selectable lists without tabular structure

​

Column Organization

​

Batch Operations

Use row selection when users need to perform batch operations on multiple rows, such as:

• Bulk delete
• Bulk status changes
• Export selected items

​

Sorting

Enable sorting only on columns where it provides value to users.

​

Pagination

​

Choose Appropriate Page Sizes

​

Row Expansion

​

Sub-Rows vs Sub-Components

​

Keep Expanded Content Focused

​

Custom Body Cells

When none of the existing body cell types fit a use case, render custom components to body cells.

​

Alternatives

​

DataTable vs ListView

Choose DataTable when data has multiple attributes that benefit from column structure. Choose ListView when displaying a simple list of selectable items.