Skip to main content

DataTable

@spartanfx/react v1.2.2

@spartanfx/react / index / DataTable

Function: DataTable()

function DataTable<T>(props): Element;

Renders a powerful, configurable data table with support for:

  • Fluent UI DetailsList and responsive tile view
  • Column filtering, sorting, and search
  • Export to Excel
  • Infinite scrolling
  • Custom field renderers
  • Dark mode theming with customizable tokens

This component is highly extensible and can be themed, localized, and dynamically updated through callbacks. Unlike ListView, DataTable uses props-based data instead of SPFx dependencies.

Type Parameters​

T​

T = any

Props​

Required​

PropertyTypeDefaultDescription
columns( | IColumn | IDataTableColumn<T>)[]-Array of columns to be rendered in the view. Can be either simplified IDataTableColumn or full IColumn definitions, or a mix of both.
itemsT[]-Array of items to display in the table

Options​

PropertyTypeDefaultDescription
availableColumns?IColumn[]-All available columns for column selector (if different from visible columns) Work alongside with viewKey to store the column configuration
currentFilters?object-Current active filters
disableFiltering?boolean-Disables column-based filtering entirely.
disableInnerInfiniteScroll?boolean-Disables the built-in IntersectionObserver infinite scroll. When true, the sentinel element is not rendered and onLoadMore is never called automatically. Useful when pagination is managed externally (e.g., by a PCF dataset) or when using the built-in pager.
disableLoadingAnimation?boolean-Disable inner loading animation
disableSorting?boolean-Disables column-based sorting entirely.
enableCellContextMenu?boolean-Enable cell context menu (right-click on cells)
enableColumnSelector?boolean-Enable the column selector feature allowing users to customize visible columns
enablePager?boolean-Enables the built-in Pager component below the table for client-side pagination. When enabled, items are sliced per page and a pagination bar is shown. Implicitly disables inner infinite scroll.
error?Error-Current error state
exportAttributeOverride?object-Optional attribute override for export (e.g., Requestor: 'title')
fieldInfo?IDataTableFieldType[]-Optional field metadata (for field renderers and tooltips)
forceTileView?boolean-Forces tile view layout regardless of screen width.
groupByLevel1?keyof T & string-Field name for level-1 grouping. When set, items are grouped by this field. Grouping is only applied in DetailsList view (not TileView) and is incompatible with the built-in pager.
groupByLevel2?keyof T & string-Field name for level-2 grouping (sub-groups within level 1). Requires groupByLevel1 to be set.
groupByLevel3?keyof T & string-Field name for level-3 grouping (sub-sub-groups within level 2). Requires groupByLevel1 and groupByLevel2 to be set.
groupsDefaultCollapsed?boolean-Whether groups should start collapsed. Defaults to false (expanded).
hasMore?boolean-Whether more items are available to load
headerText?string-Optional title or header text to show at the top of the list.
hideExport?boolean-Hides the Export to Excel button.
hideHeader?boolean-Hides the entire header toolbar (search, export, column selector, item count, custom controls).
hideSearch?boolean-Hides the search box in the header.
hideSortAndFilterButton?boolean-Hides the sort and filter button in tile view.
highlightedFieldName?string-Field to visually highlight in the tile view.
itemsPerPage?number10Number of items per page when enablePager is true.
listName?string-Optional list name for Excel export sheet naming
loading?boolean-Current loading state
loadingCount?boolean-Loading state specifically for counting total items
searchPlaceholder?string-Placeholder text for search box
searchText?string-Current search text (controlled)
selectedColumns?IColumn[]-Selected columns (controlled mode). When provided, the component won't use internal localStorage. Use with onSelectedColumnsChange to manage column selection externally.
selectionMode?SelectionMode-Optional selection mode. Default value 'none'
showItemCount?boolean-Optional showItemCount. Show the number of total items.
tileViewFilterSortPanelExclusions?string[]-Field names to exclude from filter/sort pane in tile view.
tileViewFilterSortPanelOpened?boolean-Controls whether the tile view filter/sort pane is open by default.
tileViewThreshold?number1185Threshold below which the tile view is enabled automatically.
totalItems?number-Total number of items available (for pagination display)
translatedFields?string[]-Array of field internal names that require translation of their filter values.
viewKey?string-View key for column persistence (used in localStorage key) Mandatory to save column configuration to local storage

Events & callbacks​

PropertyTypeDefaultDescription
forceReload?() => void | Promise<void>-Force reload of items and total count (useful after external CUD operations)
onDismissTileViewFilterSortPanel?() => void-Callback fired when the tile view filter/sort pane is dismissed.
onExport?() => any[] | Promise<any[]>-Callback when export to Excel is requested Returns all items matching current filters/search for export
onFilter?(fieldName, selectedValues) => void | Promise<void>-Callback when filter is applied
onGetFilterOptions?(fieldName, currentFilters) => Promise<IFilterCriteria[]>-Callback to get available filter options for a field (replacing context-based filter API)
onItemClick?(item) => void-Optional handler fired when a list item is clicked.
onLoadingStateChanged?(loading) => void-Callback triggered when the loading state changes
onLoadMore?(page?) => void | Promise<void>-Callback to load items for a specific page. When used with the built-in Pager, receives the 1-based page number. When used with infinite scroll, called without arguments.
onRefresh?() => void-Callback for refresh button
onRenderDataTableControls?() => Element-Allows injecting custom UI controls above the list (e.g., command bar, filters).
onRenderGroupHeader?(group, defaultRender) => Element-Custom group header renderer. Receives the group and a default render function. Return undefined to use the default rendering.
onRenderItemCount?(itemCount) => Element-Optional onRenderItemCount. Use this to pass a custom renderer for the item count.
onRenderItemCountNumber?(itemCount) => Element-Optional onRenderItemCountNumber. Use this to pass a custom renderer to render the item count number.
onRenderSortAndFilterButton?(hasFilters, onClick) => Element-Allows customization of the Sort/Filter button in tile view.
onRenderTile?(item, columns) => any-Optional custom tile renderer for use with tile view mode.
onSearch?(searchText) => void | Promise<void>-Callback when search text changes
onSelectedColumnsChange?(columns) => void-Callback when selected columns are changed (for persistence)
onSelectionChanged?(selectedItems) => any-Optional onSelectionChanged. Ignored if SelectionMode is set to none
onSort?(fieldName, descending) => void | Promise<void>-Callback when sort is requested
translate?(text) => string-Optional translation function for labels like buttons and filters.

Appearance & theming​

PropertyTypeDefaultDescription
appearance?AppearanceModeAppearanceMode.lightAppearance mode for theming (light or dark)
themeTokens?object-Optional theme tokens to customize DataTable appearance. CSS custom properties that override default theme values.
themeTokens.borderRadius?string-Border radius
themeTokens.colorBackground?string-Background color for main container
themeTokens.colorBorder?string-Border color
themeTokens.colorHover?string-Hover state background
themeTokens.colorPrimary?string-Primary accent color
themeTokens.colorSelected?string-Selected state background
themeTokens.colorText?string-Primary text color
themeTokens.colorTextSecondary?string-Secondary text color
themeTokens.shadow?string-Box shadow
themeTokens.spacing?string-Spacing unit
themeTokens.transition?string-Transition duration

Advanced & escape hatches​

PropertyTypeDefaultDescription
detailsListProps?Partial<IDetailsListProps>-Optional overrides for Fluent UI's DetailsList props.
exportButtonProps?object-Export button props customization
exportButtonProps.iconName?string--
exportButtonProps.text?string--
gridProps?Partial<IGridProps>-Optional Grid props for customizing tile layout in tile view Passed through to the Grid component used by TileList
pagerProps?Partial<IPagerProps>-Optional Pager props.
searchBoxProps?Partial<IExtendedSearchBoxProps>-Optional ExtendedSearchBox props.
tileListProps?Partial<ITileListProps>-Optional TileList props

Full type reference: IDataTableProps

Returns​

Element

Examples​

DataTable with only mandatory props

<DataTable
  items={items}
  columns={columns}
  onLoadMore={() => loadMoreItems()}
/>

DataTable with selection activated

<DataTable
  items={items}
  columns={columns}
  selectionMode={SelectionMode.multiple}
  onSelectionChanged={(selectedItems: any[]) => console.log(selectedItems)}
/>

DataTable with dark mode

import { DataTable, AppearanceMode } from '@spartanfx/components';

<DataTable
  items={items}
  columns={columns}
  appearance={AppearanceMode.dark}
/>

DataTable with custom theme tokens

<DataTable
  items={items}
  columns={columns}
  appearance={AppearanceMode.dark}
  themeTokens={{
    colorPrimary: '#10b981',
    colorBackground: '#111827',
    colorBorder: '#1f2937',
    colorText: '#f9fafb',
    colorHover: '#1f2937'
  }}
/>