Data Table

Guidelines
React Implementation
Blazor API Reference

Data Tables (DataGrids) organize and present structured information in rows and columns, allowing users to scan, analyze, compare, and take action on large sets of data efficiently.

Guidance

Aspect	Best Practice
Usage	Use data tables for structured data that benefits from column-based organization, sorting, filtering, or other data manipulation operations.
Content	Include clear column headers. Present data consistently. Ensure proper data alignment (text left, numbers right). Provide appropriate data density.
Behavior	Support sorting, filtering, pagination for large datasets. Allow row selection when actions apply to rows. Enable responsive behaviors for small screens.
States	Clearly indicate hover, selected, and active states. Show loading states during data fetching. Provide empty and error states.
Feedback	Highlight sorted columns. Provide visual feedback for selection, sorting operations, and filtering. Indicate loading states during data operations.
Examples	Financial data, inventory lists, user management, analytics, or any structured tabular information that requires analysis.

Best Practices

Appropriate Column Selection: Include only necessary columns to avoid overwhelming users with data.
Meaningful Organization: Arrange columns in a logical order, with most important information first.
Responsive Handling: Consider how tables adapt to different screen sizes, potentially collapsing or reorganizing on small screens.
Action Accessibility: Make row and bulk actions easily accessible while maintaining a clean interface.
Performance Optimization: Implement virtualization or pagination for large datasets to maintain performance.

Do’s and Don’ts

Do

Provide clear column headers with sorting indicators when applicable.
Align content consistently (text left, numbers right).
Include pagination, filtering, or virtualization for large datasets.
Maintain consistent row heights and data formatting.

Don't

Overload tables with too many columns.
Mix different types of information within a single column.
Rely solely on color to indicate state or meaning.
Omit empty states or loading indicators.

Additional Guidance

Psychological Impact:
- Cognitive Organization: Tables leverage our innate ability to scan and compare data in grid formats.
- Information Hierarchy: Well-designed tables help users prioritize which data to focus on first.
- Cognitive Load: Sorting, filtering, and pagination reduce the mental effort required to find specific information.

The Data Table is implemented using TanStack Table (formerly React Table) and our base Table component. This powerful combination allows you to create complex, feature-rich data tables with sorting, filtering, pagination, and row selection.

Getting Started

Install Dependencies

npm install @tanstack/react-table

Basic Implementation

A data table implementation consists of several key parts:

Column definitions
Data source
Table configuration
UI components

Here’s how to build a complete data table with sorting, filtering, pagination, and row selection:

import { useState, useEffect } from 'react'
import {
  Table,
  TableHeader,
  TableBody,
  TableHead,
  TableRow,
  TableCell,
} from '@strongtie/design-system/table'
import { Checkbox } from '@strongtie/design-system/checkbox'
import { Input } from '@strongtie/design-system/input'
import {
  Pagination,
  PaginationContent,
  PaginationItem,
  PaginationLink,
  PaginationNext,
  PaginationPrevious,
  PaginationEllipsis,
} from '@strongtie/design-system/pagination'
import {
  Select,
  SelectTrigger,
  SelectContent,
  SelectItem,
  SelectValue,
} from '@strongtie/design-system/select'
import { MdSearch, MdChevronLeft } from 'react-icons/md'
import {
  useReactTable,
  getCoreRowModel,
  flexRender,
  SortingState,
  getSortedRowModel,
  RowSelectionState,
  getFilteredRowModel,
  getPaginationRowModel,
} from '@tanstack/react-table'

Data and Column Definitions

First, define your data type and column configuration:

// Define your data type
type Person = {
  id: number
  name: string
  email: string
  role: string
  status: 'active' | 'inactive'
}

// Define your columns
const columns = [
  {
    id: 'select',
    header: ({ table }) => {
      const selectedRows = table.getSelectedRowModel().rows.length
      const totalRows = table.getRowModel().rows.length
      const checked =
        selectedRows === totalRows
          ? true
          : selectedRows === 0
            ? false
            : 'indeterminate'

      return (
        <Checkbox
          checked={checked}
          onCheckedChange={(value) => {
            if (value === 'indeterminate') {
              table.toggleAllPageRowsSelected(false)
            } else {
              table.toggleAllPageRowsSelected(!!value)
            }
          }}
          aria-label='Select all rows'
        />
      )
    },
    cell: ({ row }) => (
      <Checkbox
        checked={row.getIsSelected()}
        onCheckedChange={(checked) => row.toggleSelected(!!checked)}
        aria-label={`Select row ${row.id}`}
      />
    ),
  },
  {
    accessorKey: 'name',
    header: 'Name',
    cell: ({ row }) => (
      <div style={{ display: 'flex', alignItems: 'center' }}>
        {row.getValue('name')}
      </div>
    ),
  },
  // Add more columns as needed
]

Table Component

Now, implement your table component:

export function DataTable() {
  const [sorting, setSorting] = useState<SortingState>([])
  const [rowSelection, setRowSelection] = useState<RowSelectionState>({})
  const [globalFilter, setGlobalFilter] = useState('')

  // Set up the table
  const table = useReactTable({
    data: yourDataArray,
    columns,
    getCoreRowModel: getCoreRowModel(),
    onSortingChange: setSorting,
    getSortedRowModel: getSortedRowModel(),
    onRowSelectionChange: setRowSelection,
    enableRowSelection: true,
    getFilteredRowModel: getFilteredRowModel(),
    getPaginationRowModel: getPaginationRowModel(),
    globalFilterFn: 'includesString',
    state: {
      sorting,
      rowSelection,
      globalFilter,
    },
  })

  return (
    <div className='data-table'>
      {/* Search and controls */}
      <div className='table-controls'>
        <div className='search-box'>
          <div className='search-wrapper'>
            <Input
              type='text'
              value={globalFilter}
              onChange={(event) => setGlobalFilter(event.target.value)}
              placeholder='Search all columns...'
              className='search-input main-search'
            />
            <div className='search-icon'>
              <MdSearch aria-hidden='true' />
            </div>
          </div>
        </div>
        <div className='selected-count'>
          {`${table.getSelectedRowModel().rows.length} of ${table.getRowModel().rows.length} row(s) selected`}
        </div>
      </div>

      {/* Table */}
      <div className='table-container'>
        <Table size="md">
          <TableHeader>
            {table.getHeaderGroups().map((headerGroup) => (
              <TableRow key={headerGroup.id}>
                {headerGroup.headers.map((header) => (
                  <TableHead
                    key={header.id}
                    onClick={header.column.getToggleSortingHandler()}
                    style={{
                      cursor:
                        header.column.id !== 'select' ? 'pointer' : 'default',
                      position: 'relative',
                    }}
                  >
                    <div className='header-content'>
                      {flexRender(
                        header.column.columnDef.header,
                        header.getContext()
                      )}
                      {header.column.id !== 'select' &&
                        (header.column.getIsSorted() === 'asc' ? (
                          <MdChevronLeft className='sort-icon rotate-90' />
                        ) : header.column.getIsSorted() === 'desc' ? (
                          <MdChevronLeft className='sort-icon -rotate-90' />
                        ) : (
                          <div className='sort-icon-group'>
                            <MdChevronLeft className='sort-icon rotate-90' />
                            <MdChevronLeft className='sort-icon -rotate-90' />
                          </div>
                        ))}
                    </div>
                  </TableHead>
                ))}
              </TableRow>
            ))}
          </TableHeader>
          <TableBody>
            {table.getRowModel().rows.map((row) => (
              <TableRow
                key={row.id}
                data-state={row.getIsSelected() ? 'selected' : undefined}
              >
                {row.getVisibleCells().map((cell) => (
                  <TableCell key={cell.id}>
                    {flexRender(cell.column.columnDef.cell, cell.getContext())}
                  </TableCell>
                ))}
              </TableRow>
            ))}
          </TableBody>
        </Table>
      </div>

      {/* Pagination */}
      <div className='pagination-wrapper'>
        <div className='pagination-info'>
          <span>
            Page {table.getState().pagination.pageIndex + 1} of{' '}
            {table.getPageCount()}
          </span>
          <Select
            value={table.getState().pagination.pageSize.toString()}
            onValueChange={(value) => {
              table.setPageSize(Number(value))
            }}
          >
            <SelectTrigger style={{ width: '120px' }}>
              <SelectValue placeholder='Show...' />
            </SelectTrigger>
            <SelectContent>
              {[10, 20, 30, 40, 50].map((pageSize) => (
                <SelectItem
                  key={pageSize}
                  value={pageSize.toString()}
                >
                  Show {pageSize}
                </SelectItem>
              ))}
            </SelectContent>
          </Select>
        </div>
        <Pagination>
          <PaginationContent>
            <PaginationItem>
              <PaginationPrevious
                onClick={() => table.previousPage()}
                disabled={!table.getCanPreviousPage()}
              />
            </PaginationItem>
            {/* Logic for showing page numbers */}
            <PaginationItem>
              <PaginationNext
                onClick={() => table.nextPage()}
                disabled={!table.getCanNextPage()}
              />
            </PaginationItem>
          </PaginationContent>
        </Pagination>
      </div>
    </div>
  )
}

Features and Customization

The Data Table implementation provides several powerful features:

Sorting

Clicking on column headers toggles sorting. Add sorting to columns with getSortedRowModel().

Filtering

The global search filters across all columns. You can also add column-specific filters:

// Column-specific filter
table.getColumn('columnName')?.setFilterValue(filterValue)

Pagination

Navigate through large datasets with page controls. Customize page sizes with the Select component.

Row Selection

Select individual rows or all rows with checkboxes. Access selected rows with:

const selectedRows = table.getSelectedRowModel().rows

Custom Cell Rendering

Define custom cell rendering for any column using the cell property:

{
  accessorKey: 'status',
  header: 'Status',
  cell: ({ row }) => (
    <span className={`status ${row.original.status}`}>
      {row.original.status}
    </span>
  ),
}

Custom Styling

Apply custom styling to your data table using CSS. Create a separate SCSS file for table-specific styles:

.data-table {
  .table-controls {
    display: flex;
    justify-content: space-between;
    margin-bottom: 1rem;
  }

  .search-wrapper {
    position: relative;
  }

  .search-icon {
    position: absolute;
    top: 50%;
    right: 0.75rem;
    transform: translateY(-50%);
  }

  .sort-icon {
    width: 1rem;
    height: 1rem;
    margin-left: 0.25rem;
    &.rotate-90 {
      transform: rotate(90deg);
    }
    &.-rotate-90 {
      transform: rotate(-90deg);
    }
  }

  .pagination-wrapper {
    display: flex;
    justify-content: space-between;
    align-items: center;
    margin-top: 1rem;
  }

  .status {
    &.active {
      color: green;
    }
    &.inactive {
      color: red;
    }
  }
}

For more examples and advanced implementations, refer to the TanStack Table documentation.

Example

<StudsDataGrid @ref="grid"
              Data="@employees"
              AllowRowSelectOnRowClick="true"
              AllowSorting="true"
              AllowPaging="true"
              PageSize="4"
              ColumnWidth="200px"
              SelectionMode="DataGridSelectionMode.Multiple"
              @bind-Value="@selectedEmployees">
    <Columns>
        <StudsDataGridColumn Width="60px" Sortable="false" Filterable="false">
            <HeaderTemplate>
                <StudsCheckBox TabIndex="-1" TriState="false" TValue="bool?" Value="@(selectedEmployees == null || selectedEmployees?.Any() != true ? false : !employees.All(i => selectedEmployees.Contains(i)) ? null : employees.Any(i => selectedEmployees.Contains(i)))" Change="@(args => selectedEmployees = args == true ? employees.ToList() : null)" />
            </HeaderTemplate>
            <Template Context="data">
                <StudsCheckBox TabIndex="-1" TriState="false" Value="@(selectedEmployees != null && selectedEmployees.Contains(data))" TValue="bool" Change=@(args => { if(!allowRowSelectOnRowClick) { grid.SelectRow(data); }}) />
            </Template>
        </StudsDataGridColumn>
        <StudsDataGridColumn Property="@nameof(Employee.Photo)" Title="Employee" Sortable="false" Filterable="false">
            <Template Context="data">
                @data.FirstName @data.LastName
            </Template>
        </StudsDataGridColumn>
        <StudsDataGridColumn Property="@nameof(Employee.Title)" Title="Title" />
        <StudsDataGridColumn Property="@nameof(Employee.EmployeeID)" Title="Employee ID" />
        <StudsDataGridColumn Property="@nameof(Employee.HireDate)" Title="Hire Date" FormatString="{0:d}" />
        <StudsDataGridColumn Property="@nameof(Employee.City)" Title="City" />
        <StudsDataGridColumn Property="@nameof(Employee.Country)" Title="Country" />
    </Columns>
</StudsDataGrid>

`<StudsDataGrid>` Parameters

Data

IEnumerable<TItem>

Gets or sets the data source.

AllowSorting

bool

default:"false"

If true, columns can be sorted by clicking on the column header.

AllowPaging

bool

default:"false"

If true, the grid will display pagination controls.

PageSize

int

default:"10"

The number of rows to display per page when paging is enabled.

PageNumbersCount

int

default:"5"

Gets or sets the page numbers count.

Count

int

Gets or sets the total count of items.

ShowEmptyMessage

bool

default:"true"

If true, shows the empty message when there are no records.

ShowHeader

bool

default:"true"

If true, shows the grid headers.

ColumnWidth

string

Default width for all columns.

Caption

string

Caption text for the grid.

EmptyText

string

default:"No records to display."

Text to display when there are no records.

IsLoading

bool

default:"false"

If true, displays a loading indicator.

SelectionMode

DataGridSelectionMode

default:"DataGridSelectionMode.Single"

Specifies the selection mode behavior (Single or Multiple).

AllowRowSelectOnRowClick

bool

default:"true"

If true, clicking a row will select it.

EditMode

DataGridEditMode

default:"DataGridEditMode.Multiple"

Specifies the inline edit mode behavior (Single or Multiple).

GotoFirstPageOnSort

bool

default:"false"

If true, the grid will go to the first page when sorting is changed.

KeyProperty

string

Gets or sets the key property.

Value

IList<TItem>

Gets or sets the selected rows.

ValueChanged

EventCallback<IList<TItem>>

Callback fired when the selected rows change.

LoadChildData

EventCallback<DataGridLoadChildDataEventArgs<TItem>>

Callback used to load child data for hierarchical grids.

Sort

EventCallback<DataGridColumnSortEventArgs<TItem>>

Callback fired when a column is sorted.

Group

EventCallback<DataGridColumnGroupEventArgs<TItem>>

Callback fired when a column is grouped.

PickedColumnsChanged

EventCallback<DataGridPickedColumnsChangedEventArgs<TItem>>

Callback fired when the visible columns change.

RowSelect

EventCallback<TItem>

Callback fired when a row is selected.

RowDeselect

EventCallback<TItem>

Callback fired when a row is deselected.

RowClick

EventCallback<DataGridRowMouseEventArgs<TItem>>

Callback fired when a row is clicked.

RowDoubleClick

EventCallback<DataGridRowMouseEventArgs<TItem>>

Callback fired when a row is double-clicked.

CellClick

EventCallback<DataGridCellMouseEventArgs<TItem>>

Callback fired when a cell is clicked.

CellDoubleClick

EventCallback<DataGridCellMouseEventArgs<TItem>>

Callback fired when a cell is double-clicked.

Callback fired when a cell context menu is triggered.

KeyDown

EventCallback<KeyboardEventArgs>

Callback fired when a key is pressed in the grid.

RowEdit

EventCallback<TItem>

Callback fired when a row is edited.

RowUpdate

EventCallback<TItem>

Callback fired when a row is updated.

RowCreate

EventCallback<TItem>

Callback fired when a row is created.

RowRender

Action<RowRenderEventArgs<TItem>>

Action to customize row rendering attributes.

CellRender

Action<DataGridCellRenderEventArgs<TItem>>

Action to customize cell rendering attributes.

HeaderCellRender

Action<DataGridCellRenderEventArgs<TItem>>

Action to customize header cell rendering attributes.

FooterCellRender

Action<DataGridCellRenderEventArgs<TItem>>

Action to customize footer cell rendering attributes.

RenderAsync

Func<DataGridRenderEventArgs<TItem>, Task>

Async callback for render customization.

Render

Action<DataGridRenderEventArgs<TItem>>

Action for render customization.

LoadSettings

Action<DataGridLoadSettingsEventArgs>

Action for loading settings.

PageSizeChanged

EventCallback<int>

Callback fired when the page size changes.

LoadData

EventCallback<LoadDataArgs>

Callback for custom data loading.

Settings

DataGridSettings

Gets or sets DataGrid settings.

SettingsChanged

EventCallback<DataGridSettings>

Callback fired when settings change.

Columns

RenderFragment

Gets or sets the columns template.

HeaderTemplate

RenderFragment

Custom header template.

FooterTemplate

RenderFragment

Custom footer template.

EmptyTemplate

RenderFragment

Template to display when there are no records.

LoadingTemplate

RenderFragment

Template to display while loading.

EditTemplate

RenderFragment<TItem>

Template for row edit mode.

Template

RenderFragment<TItem>

Template for row display.

Attributes

Dictionary<string, object>

Specifies additional custom attributes that will be rendered by the component.

MouseEnter

EventCallback<ElementReference>

Gets or sets the callback that is invoked when the mouse enters an item.

MouseLeave

EventCallback<ElementReference>

Gets or sets the callback that is invoked when the mouse leaves an item.

A callback that will be invoked when the user right-clicks the component. Commonly used to display a context menu.

Culture

CultureInfo

default:"CultureInfo.CurrentCulture"

Gets or sets the culture used to display localizable data (numbers, dates). Set by default to “CultureInfo.CurrentCulture”.

Style

string

Gets or sets the inline CSS style.

Visible

bool

default:"true"

Gets or sets a value indicating whether this “T:Studs.StudsComponent” is visible. Invisible components are not rendered.

`<StudsDataGridColumn>` Parameters

Columns

RenderFragment

Child columns for grouping or composite columns.

AllowCheckBoxListVirtualization

bool

default:"true"

Whether to allow checkbox list virtualization.

UniqueID

string

Unique identifier for the column.

OrderIndex

int?

Order index for column positioning.

SortOrder

SortOrder?

Sort order for the column.

Visible

bool

default:"true"

Gets or sets a value indicating whether this column is visible.

Gets or sets the header tooltip.

Title

string

Gets or sets the column title.

Property

string

Gets or sets the property name.

SortProperty

string

Gets or sets the sort property name (if different from Property).

Width

string

Gets or sets the column width.

MinWidth

string

Gets or sets the minimum column width.

FormatString

string

Format string to apply to the column values.

CssClass

string

CSS class to apply to data cells in this column.

CalculatedCssClass

Func<StudsDataGridColumn<TItem>, TItem, string>

Function that returns a CSS class based on the item and column.

HeaderCssClass

string

CSS class to apply to the header cell of this column.

FooterCssClass

string

CSS class to apply to the footer cell of this column.

Sortable

bool

default:"true"

If false, this column cannot be sorted.

TextAlign

default:"TextAlign.Left"

The text alignment in this column.

Template

RenderFragment<TItem>

Custom cell template.

EditTemplate

RenderFragment<TItem>

Custom edit template.

IsInEditMode

Func<string, TItem, bool>

default:"DefaultIsInEditMode"

Function that determines if this column is in edit mode.

HeaderTemplate

RenderFragment

Custom header template.

FooterTemplate

RenderFragment

Custom footer template.

Type

Gets or sets the data type.

FormatProvider

IFormatProvider

Gets or sets the IFormatProvider used for FormatString.

FilterOperator

Gets or sets the filter operator.

Styling Classes

The following CSS classes are applied by the DataGrid components:

Grid Container Classes

data-grid – Main data grid container
data-grid -data – Data area wrapper containing the table

Column & Header Classes

column -icon – Icon columns for expand/collapse functionality
column -title – Column header title wrapper
column -title-content – Actual column title content
column -sortable -icon – Sort indicator icons
-sortable-column – Applied to sortable column headers

Row & Cell Classes

row -expanded-content – Expanded row content wrapper
row -expanded-template – Expanded row template container
cell -data – Data cell content wrapper
datatable -emptymessage-row – Empty state message row
datatable -emptymessage – Empty state message cell
datatable -tfoot – Table footer section

Filter Classes

cell -filter – Filter cell wrapper
cell -filter-content – Filter cell content container
cell -filter-label – Filter input/label wrapper
cell -filter-clear – Clear filter button
filter -button – Filter toggle button
grid -filter-active – Active filter state indicator
grid -filter – Filter form wrapper
grid -filter-label – Filter form labels
grid -filter-buttons – Filter action buttons container
grid -date-filter – Date-specific filter popup
overlaypanel -wrapper – Filter popup wrapper
overlaypanel -content – Filter popup content
listbox -list – Filter options list
listbox -list-wrapper – Filter list container
filter -menu-symbol – Filter operator symbols
multiselect -item – Filter menu list items
-highlight – Selected/highlighted filter option
current-filter – Active filter value display
clear-filter – Clear filter action button
apply-filter – Apply filter action button

For more examples, visit the Storybook.

Getting Started

Foundations

Components

Integration Guides

Content

Guidance

Best Practices

Do’s and Don’ts

Do

Don't

Additional Guidance

Getting Started

Install Dependencies

Basic Implementation

Data and Column Definitions

Table Component

Features and Customization

Sorting

Filtering

Row Selection

Custom Cell Rendering

Custom Styling

`<StudsDataGrid>` Parameters

`<StudsDataGridColumn>` Parameters

Styling Classes

Grid Container Classes

Column & Header Classes

Row & Cell Classes

Filter Classes

Getting Started

Foundations

Components

Integration Guides

Content

​Guidance

​Best Practices

​Do’s and Don’ts

Do

Don't

​Additional Guidance

​Getting Started

​Install Dependencies

​Basic Implementation

​Data and Column Definitions

​Table Component

​Features and Customization

​Sorting

​Filtering

​Pagination

​Row Selection

​Custom Cell Rendering

​Custom Styling

​<StudsDataGrid> Parameters

​<StudsDataGridColumn> Parameters

​Styling Classes

​Grid Container Classes

​Column & Header Classes

​Row & Cell Classes

​Filter Classes

Guidance

Best Practices

Do’s and Don’ts

Additional Guidance

Getting Started

Install Dependencies

Basic Implementation

Data and Column Definitions

Table Component

Features and Customization

Sorting

Filtering

Pagination

Row Selection

Custom Cell Rendering

Custom Styling

`<StudsDataGrid>` Parameters

`<StudsDataGridColumn>` Parameters

Styling Classes

Grid Container Classes

Column & Header Classes

Row & Cell Classes

Filter Classes