Data Table
View in Storybook
Explore interactive examples and all component variations in our Storybook.
The DataTable component provides a powerful, feature-rich table for displaying and managing large datasets. Built with advanced functionality including sorting, filtering, searching, pagination, row selection, and data export. Perfect for admin panels, user management, analytics dashboards, and any interface requiring complex data presentation.
Basic Usage
ID | Name | Email | Role | |
|---|---|---|---|---|
| 1 | John Doe | john@example.com | Admin | |
| 2 | Jane Smith | jane@example.com | User | |
| 3 | Bob Johnson | bob@example.com | Editor | |
| 4 | Alice Wilson | alice@example.com | Manager | |
| 5 | Charlie Brown | charlie@example.com | User |
Showing 1 to 5 of 5 results
With Custom Renderers
Name | Email | Phone | Status | Role | |
|---|---|---|---|---|---|
John Doe | john@example.com | +1 (555) 123-4567 | active | Admin | |
Jane Smith | jane@example.com | +1 (555) 234-5678 | inactive | User | |
Bob Johnson | bob@example.com | +1 (555) 345-6789 | pending | Editor |
Showing 1 to 3 of 3 results
With Filters and Actions
Name | Email | Status | Role | Department | Actions | |
|---|---|---|---|---|---|---|
John Doe | john@example.com | active | Admin | Engineering | ||
Jane Smith | jane@example.com | active | User | Marketing | ||
Bob Johnson | bob@example.com | inactive | Editor | Engineering | ||
Alice Wilson | alice@example.com | pending | Manager | Sales |
Showing 1 to 4 of 4 results
Loading State
Analytics Dashboard
Server-side Pagination
When data is fetched page-by-page from an API, pass the serverPagination prop instead of relying on the built-in client-side slicing. The data prop must contain only the current page's rows; the table renders them as-is and delegates page navigation to your callback.
ID | Name | Email | Role | |
|---|---|---|---|---|
| 1 | User 1 | user1@example.com | Admin | |
| 2 | User 2 | user2@example.com | User | |
| 3 | User 3 | user3@example.com | Editor | |
| 4 | User 4 | user4@example.com | Admin | |
| 5 | User 5 | user5@example.com | User |
Showing 1 to 40 of 50 results
...
Localization
All text rendered by the table can be overridden through the labels prop. Every field is optional — omitted ones fall back to the English default. This is the recommended approach for i18n.
Priority:
tools.*.label>labels.*> built-in default. Existingtoolslabel fields keep working as before.
ID | Nome | E-mail | Status | Função | |
|---|---|---|---|---|---|
| 1 | João Silva | joao@exemplo.com.br | active | Admin | |
| 2 | Maria Souza | maria@exemplo.com.br | inactive | User | |
| 3 | Carlos Lima | carlos@exemplo.com.br | pending | Editor | |
| 4 | Ana Costa | ana@exemplo.com.br | active | Editor | |
| 5 | Paulo Mendes | paulo@exemplo.com.br | pending | Admin |
Exibindo 1 a 5 de 5 registros
Properties
DataTable
| Property | Type | Description |
|---|---|---|
data | T[] | Array of data objects to display in the table. |
columns | DataTableColumn<T>[] | Column configuration array. |
searchFields | (keyof T)[] | Fields to include in search functionality. |
filters | DataTableFilter<T>[] | Filter configuration array. |
pageSize | number | Number of rows per page. Default is 40. |
loading | boolean | Whether the table is in loading state. |
className | string | Additional CSS classes for the table container. |
activeFilters | Record<string, string> | Default active filters. |
tools | DataTableTools | Configuration for table tools and features. |
labels | DataTableLabels | Override any text rendered by the table. All fields optional; omitted ones fall back to English defaults. |
serverPagination | ServerPaginationConfig | Delegates pagination to the caller. When provided, data must contain only the current page's items. |
DataTableColumn
| Property | Type | Description |
|---|---|---|
key | keyof T | Data field key for this column. |
title | string | Column header title. |
sortable | boolean | Whether this column is sortable. |
width | string | CSS width value for the column. |
align | "left" | "center" | "right" | Text alignment for the column. |
hidden | boolean | Whether the column is hidden. |
headerClassName | string | Additional CSS classes for the header cell. |
customRenderer | (value: any, row: T) => ReactNode | Custom render function for cell content. |
DataTableFilter
| Property | Type | Description |
|---|---|---|
field | keyof T | Data field to filter on. |
label | string | Display label for the filter. |
options | FilterOption[] | Available filter options. |
FilterOption
| Property | Type | Description |
|---|---|---|
label | string | Display label for the option. |
value | string | Value to filter by. |
DataTableTools
| Property | Type | Description |
|---|---|---|
search | { hide?: boolean; placeholder?: string } | Search tool configuration. |
export | { hide?: boolean; label?: string } | Export button configuration. Visible by default. |
columnSelector | { hide?: boolean } | Column visibility dropdown configuration. Visible by default. |
clearFilters | { hide?: boolean; label?: string } | Clear filters button configuration. |
rowSelector | { hide?: boolean } | Row selection checkboxes configuration. |
pagination | { label?: string } | Pagination counter template. |
DataTableLabels
Override any text displayed by the table. All fields are optional.
| Field | Default | Description |
|---|---|---|
searchPlaceholder | 'Search...' | Search input placeholder. |
exportButton | 'Export CSV' | Export button label. |
clearAllButton | 'Clear All' | Clear-all-filters button label. |
paginationCounter | 'Showing {{startIndex}} to {{endIndex}} of {{totalItems}} results' | Pagination counter template. Supports {{startIndex}}, {{endIndex}}, {{totalItems}}. |
noDataAvailable | 'No data available.' | Empty-state label when there is no data. |
noResultsWithFilters | 'No results found for the current filters.' | Empty-state label when filters produce no results. |
searchBadgePrefix | 'Search' | Prefix in the active-search badge. |
sortBadgePrefix | 'Sort' | Prefix in the active-sort badge. |
columnsButton | 'Columns' | Column-visibility dropdown trigger label. |
toggleColumnsMenuLabel | 'Toggle columns' | Column-visibility dropdown menu label. |
resetColumnsButton | 'Reset columns' | Reset column-visibility button label. |
allFilterOption | (filterLabel: string) => string | Factory for the "All" option in filter dropdowns. Default: returns "All {filterLabel}". |
rowSelectedSingular | 'row selected' | Selection info label (singular). |
rowSelectedPlural | 'rows selected' | Selection info label (plural). |
clearSelectionButton | 'Clear selection' | Clear-selection button label. |
ServerPaginationConfig
| Property | Type | Description |
|---|---|---|
totalItems | number | Total number of items on the server. |
totalPages | number | Total number of pages on the server. |
currentPage | number | Current active page (controlled externally). |
onPageChange | (page: number) => void | Called when the user navigates to a different page. |
Ref Methods
The DataTable component exposes several methods through a ref:
| Method | Type | Description |
|---|---|---|
getSelectedItems | () => T[] | Get array of currently selected items. |
clearSelection | () => void | Clear all row selections. |
getSelectionCount | () => number | Get count of selected rows. |
selectItems | (ids: string[]) => void | Select specific items by ID. |
getFilteredData | () => T[] | Get current filtered dataset. |
resetFilters | () => void | Reset all filters and search. |
exportData | (filename?: string) => void | Export current data to CSV. |
goToPage | (page: number) => void | Navigate to specific page. In server pagination mode, calls serverPagination.onPageChange. |
refresh | () => void | Refresh the table data. |
Accessibility
The DataTable component includes comprehensive accessibility features:
- Keyboard Navigation - Full keyboard support for sorting, filtering, and selection
- Screen Reader Support - Proper ARIA labels and table semantics
- Focus Management - Clear focus indicators and logical tab order
- Sort Indicators - Visual and audible sort direction indicators
- Loading States - Proper loading announcements for screen readers
- Selection States - Clear indication of selected rows and bulk actions
Common Use Cases
The DataTable component is perfect for:
- User Management - Admin panels with user lists and actions
- Analytics Dashboards - Metrics and performance data display
- Content Management - Articles, posts, and media management
- E-commerce - Product catalogs and order management
- Financial Data - Transaction lists and financial reports
- System Logs - Error logs and activity monitoring
- Inventory Management - Stock levels and product tracking
Best Practices
- Performance - Use pagination for large datasets (1000+ rows)
- Search Fields - Include relevant fields in search configuration
- Custom Renderers - Use for complex data formatting and actions
- Loading States - Always show loading indicators for async operations
- Error Handling - Implement proper error states and retry mechanisms
- Responsive Design - Consider mobile layouts and horizontal scrolling
- Export Functionality - Provide data export for user convenience
- Accessibility - Test with keyboard navigation and screen readers