); } ``` `react-dnd` provides a way to separate `dragRef` and `dropRef` to use them on different DOM elements. It can be useful when there are multiple actionable elements in table rows. DraggableRowWithHandle}> ```jsx import { useDrag, useDrop } from 'react-dnd'; import { useForkRef } from '@gemini-suite/vera-react'; const DraggableRowWithHandle = React.forwardRef( ({ row, reorderRow, children, ...delegated }, forwardedRef) => { const [{ isOver }, dropRef] = useDrop({ accept: 'row', drop: draggedRow => reorderRow(draggedRow.id, row.id), collect: monitor => ({ isOver: monitor.isOver() }) }); const [{ isDragging }, dragRef, previewRef] = useDrag({ item: { id: row.id }, type: 'row', collect: monitor => ({ isDragging: monitor.isDragging() }) }); const composedRef = useForkRef(forwardedRef, dropRef, previewRef); const tableRowStatus = isDragging ? 'dragging' : isOver ? 'dropTarget' : undefined; return ( {children} ); } ); ``` ```jsx () => { const [data, setData] = React.useState([ { id: 1, name: 'Torvald Halvor', comment: 'Shortbread gummies bear claw liquorice liquorice candy chupa chups cheesecake gingerbread.', office: 'Oslo' }, { id: 2, name: 'Mikael Rikard', comment: 'Brownie icing jelly beans macaroon apple pie bear claw candy canes.', office: 'Berlin' }, { id: 3, name: 'Ragnhild Tine', comment: 'Gummi bears lollipop biscuit apple pie pudding wafer.', office: 'Munich' }, { id: 4, name: 'Jan Kowalski', comment: 'Liquorice candy chupa chups cheesecake.', office: 'Warsaw' } ]); const reorderRow = (draggedRowId, targetRowId) => { const copy = [...data]; const firstIndex = copy.findIndex(a => a.id === draggedRowId); const secondIndex = copy.findIndex(a => a.id === targetRowId); [copy[firstIndex], copy[secondIndex]] = [ copy[secondIndex], copy[firstIndex] ]; setData(copy); }; return ( {'Drag'} {'ID'} {'Name'} {'Comment'} {'Office'} {'Actions'} {data.map(row => ( {row.id} {row.name} {row.comment} {row.office} } onSelect={() => {}} > {'Edit'} ))} ); }; ``` `dragRef` and `dropRef` can be merged into one `ref` which can be useful to make whole rows draggable. DraggableRow}> ```jsx import { useDrag, useDrop } from 'react-dnd'; import { useForkRef } from '@gemini-suite/vera-react'; const DraggableRow = React.forwardRef( ({ row, reorderRow, children, ...delegated }, forwardedRef) => { const [{ isOver }, dropRef] = useDrop({ accept: 'row', drop: draggedRow => reorderRow(draggedRow.id, row.id), collect: monitor => ({ isOver: monitor.isOver() }) }); const [{ isDragging }, dragRef] = useDrag({ item: { id: row.id }, type: 'row', collect: monitor => ({ isDragging: monitor.isDragging() }) }); const composedRef = useForkRef(forwardedRef, dragRef, dropRef); const tableRowStatus = isDragging ? 'dragging' : isOver ? 'dropTarget' : undefined; return ( ); } ); ``` ```jsx () => { const [data, setData] = React.useState([ { id: 1, name: 'Torvald Halvor', comment: 'Shortbread gummies bear claw liquorice liquorice candy chupa chups cheesecake gingerbread.', office: 'Oslo' }, { id: 2, name: 'Mikael Rikard', comment: 'Brownie icing jelly beans macaroon apple pie bear claw candy canes.', office: 'Berlin' }, { id: 3, name: 'Ragnhild Tine', comment: 'Gummi bears lollipop biscuit apple pie pudding wafer.', office: 'Munich' }, { id: 4, name: 'Jan Kowalski', comment: 'Liquorice candy chupa chups cheesecake.', office: 'Warsaw' } ]); const reorderRow = (draggedRowId, targetRowId) => { const copy = [...data]; const firstIndex = copy.findIndex(a => a.id === draggedRowId); const secondIndex = copy.findIndex(a => a.id === targetRowId); [copy[firstIndex], copy[secondIndex]] = [ copy[secondIndex], copy[firstIndex] ]; setData(copy); }; return ( {'ID'} {'Name'} {'Comment'} {'Office'} {data.map(row => ( {row.id} {row.name} {row.comment} {row.office} ))} ); }; ``` --- ## Integration with TanStack Table **Table** component consists of lightweight, "primitive" building blocks designed for composability. Primitives are low-level components that assume as little as possible about their usage and they don't own any complex state. This works well for simple or static tables, but there are instances where functionality such as sorting, search, filtering, [virtualization](https://tanstack.com/virtual/v3) or pagination are required. This kind of functionality is out of scope for the **Table** component, as the spectrum of possible use-cases is too broad for a single component to cover effectively. We aim to avoid monolithic components with a lot of assumptions about how you use them and increased API surface area, i.e. endless prop configuration. Whilst the **Table** component is limited out of the box, these same limitations make it very easy to integrate with third-party libraries which offer advanced functionality. One such library that we recommend is [TanStack Table](https://tanstack.com/table/v8). It is a [headless UI library](https://www.merrickchristensen.com/articles/headless-user-interface-components/), which supplies you with functions, state and utilities to add more advanced functionality and interactions to your tables. It does not bring any user interface or styles itself, making it a perfect extension for Vera's **Table**. Examples below show how to combine some common [TanStack Table](https://tanstack.com/table/v8) features with Vera's **Table**. To use TanStack Table features, you should install `@tanstack/react-table` package in your project. ```bash npm install @tanstack/react-table --save # or yarn add @tanstack/react-table ``` For a more comprehensive, full-featured demo of a data table built using [TanStack Table](https://tanstack.com/table/v8) and **Table** component, be sure to check out [our Storybook](https://next--698f15fa99e7b146f9002f64.chromatic.com/?path=/story/demos-datatable--default). ### Basic ```js import { flexRender, getCoreRowModel, useReactTable, createColumnHelper } from '@tanstack/react-table'; ``` ```jsx () => { const columnHelper = createColumnHelper(); const columns = React.useMemo( () => [ columnHelper.accessor('id', { header: 'ID', cell: ({ getValue }) => ( {getValue()} ), meta: { width: 120 } }), columnHelper.accessor('name', { header: 'Name', cell: ({ getValue }) => ( {getValue()} ), meta: { minWidth: 200 } }), columnHelper.accessor('status', { header: 'Status', cell: ({ getValue }) => { const label = getValue(); return ( {label} ); }, meta: { minWidth: 120, maxWidth: 140 } }), columnHelper.accessor('host', { header: 'Host', cell: ({ getValue }) => ( {getValue()} ), meta: { minWidth: 180 } }), columnHelper.display({ id: '_actions', header: () => {'Actions'}, cell: ({ row }) => ( }> {'Details'} {row.original.status === 'Running' ? ( }> {'Stop'} ) : ( }> {'Start'} )} ), meta: { align: 'right', width: 60 } }) ], [] ); const data = React.useMemo( () => [ { id: 'b35ac3bd46', name: 'APP1 Production API', status: 'Running', host: 'testhost:5001' }, { id: 'mk35op153l', name: 'APP1 Test API', status: 'Down', host: 'testhost:5002' }, { id: 'b6s9dc567e', name: 'APP2 Production API', status: 'Down', host: 'testhost-secondary:5001' }, { id: 'z0s93dpl21', name: 'APP2 Development API', status: 'Running', host: 'testhost-secondary:5002' }, { id: 'gh6j3s03de', name: 'Server Configuration API', status: 'Running', host: 't3.company.server.configuration:7000' } ], [] ); const table = useReactTable({ data, columns, getCoreRowModel: getCoreRowModel() }); return ( {table.getFlatHeaders().map(header => ( {flexRender(header.column.columnDef.header, header.getContext())} ))} {table.getRowModel().rows.map(row => ( {row.getVisibleCells().map(cell => ( {flexRender(cell.column.columnDef.cell, cell.getContext())} ))} ))} ); }; ``` ### Sorting columns Use [TanStack Table Sorting API](https://tanstack.com/table/v8/docs/api/features/sorting) together with `onClick` and `sort` properties on `Table.ColumnHeader` to render the UI for a sort indicator and allow the user to change the sort order of the data. You should only use client-side sorting if your data set is small and exists in-memory, otherwise sorting should be implemented by sorting in the actual database. Custom sorting icon can be provided with `sortIndicator` attribute. Check different icon by sorting `Name` column below. Table data can be sorted by multiple columns by clicking on a column header while holding down the shift key. This is controlled with the [enableMultiSort property](https://tanstack.com/table/v8/docs/api/features/sorting#enablemultisort-1). ```js import { flexRender, getCoreRowModel, getSortedRowModel, useReactTable, createColumnHelper } from '@tanstack/react-table'; ``` ```jsx () => { const columnHelper = createColumnHelper(); const columns = React.useMemo( () => [ columnHelper.accessor('name', { header: 'Name', cell: ({ getValue }) => ( {getValue()} ) }), columnHelper.accessor('status', { header: 'Status', cell: ({ getValue }) => { const label = getValue(); return ( {label} ); }, meta: { maxWidth: 150 } }), columnHelper.accessor('host', { header: 'Host', cell: ({ getValue }) => ( {getValue()} ) }), columnHelper.accessor('time', { header: () => ( {'Uptime'} {'hours'} ), cell: ({ getValue }) => ( {getValue()} ), meta: { align: 'right', maxWidth: 120 } }) ], [] ); const data = React.useMemo( () => [ { id: 'b35ac3bd46', name: 'APP1 Production API', status: 'Running', host: 'testhost:5001', time: '4338' }, { id: 'mk35op153l', name: 'APP1 Test API', status: 'Down', host: 'testhost:5002', time: '10' }, { id: 'b6s9dc567e', name: 'APP2 Production API', status: 'Down', host: 'testhost-secondary:5001', time: '51' }, { id: 'z0s93dpl21', name: 'APP2 Development API', status: 'Running', host: 'testhost-secondary:5002', time: '122' }, { id: 'gh6j3s03de', name: 'Server Configuration API', status: 'Running', host: 't3.company.server.configuration:7000', time: '2510' } ], [] ); const [sorting, setSorting] = React.useState([]); const table = useReactTable({ data, columns, state: { sorting }, onSortingChange: setSorting, getCoreRowModel: getCoreRowModel(), getSortedRowModel: getSortedRowModel() }); return ( {table.getFlatHeaders().map(header => ( ) : undefined } > {flexRender(header.column.columnDef.header, header.getContext())} ))} {table.getRowModel().rows.map(row => ( {row.getVisibleCells().map(cell => ( {flexRender(cell.column.columnDef.cell, cell.getContext())} ))} ))} ); }; ``` ### Filtering Filtering data can be implemented with [TanStack Table Filters API](https://tanstack.com/table/v8/docs/api/features/filters). Table data can be filtered globally with use of `globalFilter` prop or it can be column filtered with `columnFilters`. ```js import { flexRender, getCoreRowModel, getFilteredRowModel, useReactTable, createColumnHelper } from '@tanstack/react-table'; ``` ```jsx () => { const columnHelper = createColumnHelper(); const columns = React.useMemo( () => [ columnHelper.accessor('name', { header: 'Name', cell: ({ getValue }) => ( {getValue()} ) }), columnHelper.accessor('status', { header: 'Status', id: 'status', enableGlobalFilter: false, cell: ({ getValue }) => { const label = getValue(); return ( {label} ); } }), columnHelper.accessor('host', { header: 'Host', cell: ({ getValue }) => ( {getValue()} ) }) ], [] ); const data = React.useMemo( () => [ { id: 'b35ac3bd46', name: 'APP1 Production API', status: 'Running', host: 'testhost:5001' }, { id: 'mk35op153l', name: 'APP1 Test API', status: 'Down', host: 'testhost:5002' }, { id: 'b6s9dc567e', name: 'APP2 Production API', status: 'Down', host: 'testhost-secondary:5001' }, { id: 'z0s93dpl21', name: 'APP2 Development API', status: 'Running', host: 'testhost-secondary:5002' }, { id: 'gh6j3s03de', name: 'Server Configuration API', status: 'Running', host: 't3.company.server.configuration:7000' }, { id: 'h5fhvdfv5f', name: 'Services Configuration API', status: 'Down', host: 't1.company.services.configuration:6000' }, { id: 'p0d39c75vl', name: 'DB Configuration API', status: 'Running', host: 't2.company.db.conf:8002' } ], [] ); const [filterValue, setFilterValue] = React.useState(''); const [globalFilter, setGlobalFilter] = React.useState(''); const [columnFilters, setColumnFilters] = React.useState([]); const debouncedFilterValue = useDebouncedValue(filterValue, 300); const [isFilterMenuOpen, setIsFilterMenuOpen] = React.useState(false); React.useEffect(() => { setGlobalFilter(debouncedFilterValue); }, [debouncedFilterValue]); const table = useReactTable({ data, columns, state: { columnFilters, globalFilter }, onGlobalFilterChange: setGlobalFilter, onColumnFiltersChange: setColumnFilters, getCoreRowModel: getCoreRowModel(), getFilteredRowModel: getFilteredRowModel() }); const rowsSize = table.getCoreRowModel().rows.length; const handleResetFilter = () => { setFilterValue(''); setGlobalFilter(''); setColumnFilters([]); }; return ( 0 ? `Search ${rowsSize} rows` : 'Search'} className="maw5" type="search" leadingVisual={} value={filterValue} onChange={event => setFilterValue(event.target.value)} /> } > {'Filter status'} {table.getColumn('status')?.getFilterValue() ? ( {`:`} {table.getColumn('status').getFilterValue()} ) : null} table.getColumn('status')?.setFilterValue(value) } > {'All'} {'Running'} {'Down'} {table.getFlatHeaders().map(header => ( {flexRender( header.column.columnDef.header, header.getContext() )} ))} {table.getRowModel().rows.length > 0 ? ( {table.getRowModel().rows.map(row => ( {row.getVisibleCells().map(cell => ( {flexRender( cell.column.columnDef.cell, cell.getContext() )} ))} ))} ) : ( {'No matches.'} {'We can’t find a match for the provided filter query.'} )} ); }; ``` ### Selecting rows Rows selection can be implemented with [Row Selection API](https://tanstack.com/table/v8/docs/api/features/row-selection). In the example below batch actions will be shown upon rows selection. ```js import { flexRender, getCoreRowModel, useReactTable, createColumnHelper } from '@tanstack/react-table'; ``` ```jsx () => { const columnHelper = createColumnHelper(); const columns = React.useMemo( () => [ columnHelper.display({ id: '_select', header: ({ table }) => ( { table.getIsSomeRowsSelected() ? table.resetRowSelection() : table.toggleAllRowsSelected(); }} /> ), cell: ({ row }) => ( ), meta: { width: 40 } }), columnHelper.accessor('name', { header: 'Name', cell: ({ getValue }) => ( {getValue()} ), meta: { minWidth: 160 } }), columnHelper.accessor('status', { header: 'Status', cell: ({ getValue }) => { const label = getValue(); return ( {label} ); }, meta: { minWidth: 120, maxWidth: 160 } }), columnHelper.accessor('host', { header: 'Host', cell: ({ getValue }) => ( {getValue()} ), meta: { minWidth: 200 } }) ], [] ); const data = React.useMemo( () => [ { id: 'b35ac3bd46', name: 'APP1 Production API', status: 'Running', host: 'testhost:5001' }, { id: 'mk35op153l', name: 'APP1 Test API', status: 'Down', host: 'testhost:5002' }, { id: 'b6s9dc567e', name: 'APP2 Production API', status: 'Down', host: 'testhost-secondary:5001' }, { id: 'z0s93dpl21', name: 'APP2 Development API', status: 'Running', host: 'testhost-secondary:5002' }, { id: 'gh6j3s03de', name: 'Server Configuration API', status: 'Running', host: 't3.company.server.configuration:7000' } ], [] ); const [rowSelection, setRowSelection] = React.useState({}); const table = useReactTable({ data, columns, state: { rowSelection }, onRowSelectionChange: setRowSelection, getCoreRowModel: getCoreRowModel() }); const rowsSize = table.getCoreRowModel().rows.length; const selectedRowsSize = table.getSelectedRowModel().rows.length; return ( {table.getFlatHeaders().map(header => ( {flexRender(header.column.columnDef.header, header.getContext())} ))} {table.getRowModel().rows.map(row => ( {row.getVisibleCells().map(cell => ( {flexRender(cell.column.columnDef.cell, cell.getContext())} ))} ))} {selectedRowsSize > 0 && ( {selectedRowsSize} of {rowsSize} row(s) selected. )} ); }; ``` ### Pagination With help of [Pagination component](/components/pagination) to display the pagination UI and [TanStack Pagination API](https://tanstack.com/table/v8/docs/api/features/pagination), larger table data sets can be split into pages. Often pagination is performed server-side and `Table` already receives only data for specific page. In that case [manualPagination property](https://tanstack.com/table/v8/docs/api/features/pagination#manualpagination) is helpful. Be mindful to provide an `aria-description` attribute on the `Table` to let the assistive technologies announce current pagination state. ```js import { flexRender, getCoreRowModel, getPaginationRowModel, useReactTable, createColumnHelper } from '@tanstack/react-table'; ``` ```jsx () => { const columnHelper = createColumnHelper(); const columns = React.useMemo( () => [ columnHelper.accessor('name', { header: 'Host name', cell: ({ getValue }) => ( {getValue()} ), meta: { minWidth: 200 } }), columnHelper.accessor('ipAddress', { header: 'IP Address', cell: ({ getValue }) => ( {getValue()} ), meta: { minWidth: 140, maxWidth: 160 } }), columnHelper.accessor('port', { header: 'Port', cell: ({ getValue }) => ( {getValue()} ), meta: { minWidth: 80, maxWidth: 100 } }), columnHelper.accessor('status', { header: 'Status', cell: ({ getValue }) => { const label = getValue(); return ( {label} ); }, meta: { minWidth: 120, maxWidth: 160 } }) ], [] ); const data = React.useMemo( () => Array(120) .fill() .map(() => ({ name: faker.internet.domainName(), ipAddress: faker.internet.ip(), port: faker.internet.port(), status: faker.helpers.arrayElement(['Running', 'Down']) })), [] ); const [{ pageIndex, pageSize }, setPagination] = React.useState({ pageIndex: 0, pageSize: 10 }); const pagination = React.useMemo( () => ({ pageIndex, pageSize }), [pageIndex, pageSize] ); const table = useReactTable({ data, state: { pagination }, pageCount: Math.ceil(data.length / pageSize), onPaginationChange: setPagination, columns, getCoreRowModel: getCoreRowModel(), getPaginationRowModel: getPaginationRowModel() }); const pageCount = table.getPageCount(); const paginationRange = usePagination({ currentPage: pageIndex, pageCount: table.getPageCount() }); const pageSizeOptions = [10, 25, 50].map(s => ({ value: s.toString(), label: s.toString() })); const pageCursorStart = pageIndex * pageSize + 1; const pageCursorEnd = Math.min(pageCursorStart + pageSize - 1, data.length); return ( {table.getFlatHeaders().map(header => ( {flexRender(header.column.columnDef.header, header.getContext())} ))} {table.getRowModel().rows.map(row => ( {row.getVisibleCells().map(cell => ( {flexRender(cell.column.columnDef.cell, cell.getContext())} ))} ))} table.previousPage()} isDisabled={!table.getCanPreviousPage()} /> {paginationRange.map((pageNumber, index) => { if (pageNumber === -1) { return ( ); } return ( table.setPageIndex(pageNumber - 1)} > {pageNumber} ); })} table.nextPage()} disabled={!table.getCanNextPage()} /> {`${pageCursorStart}–${pageCursorEnd} of ${data.length}`} {'Show'}