import { DataTable } from '@uhg-abyss/web/ui/DataTable';
import { useDataTable } from '@uhg-abyss/web/hooks/useDataTable';

This is a migration guide from V1 DataTable to the new DataTable. DataTable is a complete rewrite of the V1 DataTable component. While this means migrating will require more effort compared to other V2 components, the benefits of the new DataTable are worth it.

Before digging into the details, here are some of the changes and benefits of the new DataTable:

Benefits

Sub-componentization

• DataTable is now broken up into sub-components. This will allow for more flexibility and customization.

List of sub-components:

• DataTable.DownloadDropdown
• DataTable.Table
• DataTable.GlobalFilter
• DataTable.TableSettingsDropdown
• DataTable.Pagination
• DataTable.BulkActionsDropdown
• DataTable.SlotWrapper

Column filtering

• Filtering can now be achieved at the column level. This means you no longer need to open a modal dialog to filter an individual column. Instead, you can filter directly from the column header.
• There are now two types of column filtering: 'basic' and 'advanced'.
  • Basic filtering provides a TextInput, SelectInput, or a DateInput depending on the column type.
  • Advanced filtering uses a Popover that allows for multiple conditions to be added.
    • We have also added the ability to use the disjunctive operator (OR) in addition to the conjunctive operator (AND) when applying multiple conditions to a single column.

Custom filtering and sorting logic

• Custom global or column filtering and sorting logic can be seamlessly integrated into the DataTable component. If the built-in logic does not work for your use case, you can simply provide your own functionality.

Editable cells

• Cells within the table can now be made editable, meaning that users can edit the contents of a cell directly within the table.
  • These editable cells are able to be a TextInput, SelectInput, or DateInput, depending on the column type.

Virtualization

• Virtualization is completely built into the table. This allows for a smoother experience when working with very large datasets.

Server-side pagination

• We have completely reworked the server-side API. Instead of using a built in apiPaginationCall function as before, we now provide teams complete control over the API logic.
  • This allows for a more seamless experience when working with server-side data and gives you full control over the API call(s) and loading state.
  • We recommend teams use TanStack Query for server-side data fetching, as much of the DataTable is built on TanStack libraries, but you are free to use any other library you prefer.

Sticky/pinned columns

• Columns can now be pinned to the left or right side of the table. This allows for a more seamless experience when working with datasets with many columns.
  • Pinned columns will always be visible, even when scrolling horizontally.

Drag-and-drop columns

• Columns can now be reordered by dragging and dropping them, just as rows could be reordered in the V1 DataTable.
  • The ability to reorder rows is still available.

---

Migrating

As noted above, migrating to the DataTable will require more effort than migrating to other components. After reading through the benefits above, it should be clear why.

Before beginning the migration, we recommend reading through the DataTable documentation to get a better understanding of how the new component works.

Troubleshooting

If you encounter any issues during the migration process, please post your questions, problems, or findings on GitHub Discussions. This will allow all teams to see, respond to, and benefit from shared solutions. If someone has already asked a similar question, consider adding your insights or upvoting the existing discussion rather than creating a duplicate. This helps keep the conversation organized and makes it easier for everyone to find relevant information.

Go to the V2DataTable - Migration Support Discussion

import { DataTable } from '@uhg-abyss/web/ui/DataTable';

Same in V1 and V2

Quick Overview

The DataTable component now accepts sub-components for better organization and flexibility.

DataTable changes

V1 Prop	Status	Migration Details
headingLevel	Modified	The headingLevel prop has been modified to accept a number instead of a string.

import { useDataTable } from '@uhg-abyss/web/hooks/useDataTable';

Same in V1 and V2

Quick Overview

The useDataTable hook has seen significant changes to its API to enhance usability and flexibility. This first section outlines simple prop changes, while further sections focus on more complex changes based on the prop.

useDataTable changes

V1 Prop	Status	Migration Details
initialColumns	Modified	See initialColumns prop changes below in separate table.
initialData	Modified	The initialData now requires a unique identifier field for each row to ensure proper row identification. By default, this field is uniqueId, or provide rowIdKey to use a different field name. Note: uniqueId is deprecated, but still supported for backwards compatibility.
showColumnSort	Removed	Sorting is now disabled by default. Use the tableConfig.enableSorting prop to enable sorting. Sorting documentation
showGlobalFilter	Removed	Teams will need to use the <DataTable.GlobalFilter /> sub-component.
customHeaderSection	Removed	The table is now a sub-component so teams can create their own custom content to be placed above the table.
showDownloadButton	Removed	Teams will need to use the <DataTable.DownloadDropdown /> sub-component.
showFilterDataset	Removed	Filtering is now handled through the column header. Filtering documentation
showFullscreenButton	Removed	This is no longer supported. Teams can implement their own fullscreen functionality if needed.
showSelection	Removed	To enable multi-selection checkboxes, set selectColumnConfig.selectionMode to 'multi'. To disable row selection for certain rows, use the tableConfig.enableRowSelection prop.
defaultSelectedRows	Removed	To set the default selected rows, use the initialStateConfig. Setting default selected rows documentation
singleSelection	Removed	To enable single-selection set selectColumnConfig.selectionMode to 'single'. To disable row selection for certain rows, use the tableConfig.enableRowSelection prop.
bulkActions	Removed	Bulk actions have been moved to the <DataTable.BulkActionsDropdown /> sub-component. DataTable.BulkActionsDropdown documentation
individualActions	Removed	Individual row actions have been moved to the actionColumnConfig. The only feature that is no longer available is the ability to render a link, but equivalent functionality is still possible using the new config for all other functionality. Individual row actions documentation
showPagination	Removed	Teams will need to use the <DataTable.Pagination /> sub-component.
pageSizeOptions	Removed	Use the paginationConfig.pageSizeOptions prop to adjust page size options.
defaultPage	Removed	Teams now control pagination state by using the tableConfig prop. Pagination documentation
enableGroupBy	Removed	To enable grouping, use the tableConfig. Grouping documentation
renderSubComponent	Removed	To enable renderSubComponent, use the expandColumnConfig. Sub-component documentation
showExpansion	Removed	To enable sub-row expansion, use the expandColumnConfig. Sub-rows documentation
initialGlobalFilter	Removed	Teams now have full control over the global filter state. Global filtering documentation
showTableSettings	Removed	Hiding empty columns and changing row height can be achieved through the <DataTable.TableSettingsDropdown /> sub-component.
showColumnVisibilityConfig	Removed	Table settings drawer was removed. Column visibility can still be achieved through the <DataTable.TableSettingsDropdown /> sub-component or header actions dropdown.
onColumnVisibilityClose	Removed	Table settings drawer was removed. Column visibility can still be achieved through the <DataTable.TableSettingsDropdown /> sub-component or header actions dropdown.
onColumnVisibilityOpen	Removed	Table settings drawer was removed. Column visibility can still be achieved through the <DataTable.TableSettingsDropdown /> sub-component or header actions dropdown.
reorderRows	Removed	Use the dragAndDropConfig.enableRowReorder prop to enable row reordering.
onRowOrderChange	Removed	Use the dragAndDropConfig prop and its onRowsReordered callback to get notified when the row order changes. The callback provides old and new indexes as well as previous and updated data.
uniqueStorageId	Removed	Teams will need to manage their own storage. DataTable was opened up so teams can use their own storage solution.

useDataTable.initialColumns prop changes

V1 Prop	Status	Migration Details
Header	Renamed	Header → header
Cell	Renamed	Cell → cell
Footer	Renamed	Footer → footer
accessor	Renamed	accessor → accessorKey
canToggleVisibility	Renamed	canToggleVisibility → enableHiding
disableResizing	Renamed	disableResizing → enableResizing
minWidth	Renamed	minWidth → minSize
width	Renamed	width → size
maxWidth	Renamed	maxWidth → maxSize
disableSortBy	Renamed	disableSortBy → enableSorting
sortType	Renamed	sortType → sortingFn. The sortingFn accepted values have changed. Teams can now pass in their own sorting functions. Refer to the sorting section for details.
isHiddenByDefault	Removed	Teams have full control over column visibility. Use tableConfig for column visibility.
label	Removed	The label prop was removed. Instead, use meta.headerLabel. This will be used in various places and is especially important for when your header is not a string.
showColumn	Removed	Teams have full control over column visibility. Use tableConfig for column visibility.
hiddenDefaultFilters	Removed	Filtering logic is now handled through the columnFilterConfig prop. Filtering documentation
customAPIFilters	Removed	Filtering logic is now handled through the columnFilterConfig prop. Filtering documentation

V1

import { useDownloadCsv } from '@uhg-abyss/web/hooks/useDataTable';

V2

import { downloadCsv } from '@uhg-abyss/web/tools/downloadCsv';

Changed from V1

Quick Overview

The CSV download helper has moved from being provided by the useDataTable hook to a standalone downloadCsv utility. Teams should call the function directly rather than retrieving it from the table hook.

CSV Download changes

V1 Prop	Status	Migration Details
useDownloadCsv	Removed	useDownloadCsv is no longer provided by useDataTable. Use the standalone downloadCsv function instead.