The @keyvaluesystems/multilevel-table is a flexible and customizable multi-level table component for React applications. It provides comprehensive support for displaying hierarchical data with features like sorting, filtering, and pagination. This documentation provides detailed information on how to install, configure, and use the component effectively.
You can install the component from npm:
npm install @keyvaluesystems/multilevel-tableor from yarn:
yarn add @keyvaluesystems/multilevel-table- React v16.8+
- TypeScript (recommended)
Here's a basic example of how to use the MultiLevelTable component:
import { MultiLevelTable } from '@keyvaluesystems/multilevel-table';
const data = [
{
id: 1,
name: 'Parent 1',
value: 100,
status: 'active',
children: [
{
id: 2,
name: 'Child 1',
value: 50,
status: 'pending',
},
{
id: 3,
name: 'Child 2',
value: 50,
status: 'completed',
},
],
},
];
const columns = [
{
key: 'name',
title: 'Name',
filterable: true,
sortable: true,
width: '25%',
},
{
key: 'value',
title: 'Value',
filterable: true,
sortable: true,
width: '20%',
render: (value) => `$${value}`,
},
{
key: 'status',
title: 'Status',
filterable: true,
sortable: true,
width: '15%',
render: (value) => (
<span style={{
padding: '4px 8px',
borderRadius: '4px',
backgroundColor: value === 'active' ? '#e6ffe6' :
value === 'pending' ? '#fff3e6' : '#e6f3ff',
color: value === 'active' ? '#006600' :
value === 'pending' ? '#cc7700' : '#0066cc'
}}>
{value}
</span>
),
},
];
function App() {
return (
<MultiLevelTable
data={data}
columns={columns}
pageSize={10}
/>
);
}The MultiLevelTable component accepts the following props:
| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
| data | DataItem[] | Yes | - | Array of data objects to display in the table |
| columns | Column[] | Yes | - | Array of column configurations |
| pageSize | number | No | 10 | Number of rows to display per page |
| theme | ThemeProps | No | - | Custom theme object for styling the table |
| renderCustomPagination | function | No | null | Custom pagination component render function |
| sortable | boolean | No | false | Enable/disable sorting functionality |
| ascendingIcon | ReactNode | No | - | Custom icon for ascending sort |
| descendingIcon | ReactNode | No | - | Custom icon for descending sort |
| expandIcon | ReactNode | No | - | Custom icon for expanding rows |
| selectable | boolean | No | false | Enable/disable row selection |
| Prop | Type | Required | Description |
|---|---|---|---|
| selectionState | SelectionState | Yes | Current selection state with selected rows and all selected flag |
| searchTerm | string | Yes | Current search term for filtering data |
| selectedFilterValues | Set<string | number> | Yes | Currently selected filter values |
| deletePopup | object | Yes | Delete confirmation popup state (isOpen, itemId, itemName) |
| bulkDeletePopup | object | Yes | Bulk delete confirmation popup state (isOpen, selectedCount) |
| openDropdowns | Set | Yes | Set of currently open dropdown IDs |
| expandedRows | Set<string | number> | Yes | Set of currently expanded row IDs |
| Prop | Type | Description |
|---|---|---|
| onSearchChange | (searchTerm: string) => void | Updates the search term for filtering data |
| onFilterChange | (values: Set<string | number>) => void | Updates the selected filter values |
| onDeleteClick | (itemId: string | number, itemName: string) => void | Handles delete button click for a specific row |
| onDeleteConfirm | () => void | Confirms the delete action for the selected row |
| onDeleteCancel | () => void | Cancels the delete action and closes popup |
| onBulkDeleteClick | () => void | Handles bulk delete button click for selected rows |
| onBulkDeleteConfirm | () => void | Confirms the bulk delete action for selected rows |
| onBulkDeleteCancel | () => void | Cancels the bulk delete action and closes popup |
| onDropdownToggle | (buttonId: string, isOpen: boolean) => void | Toggles dropdown open/close state for action buttons |
| onDropdownClose | (buttonId: string) => void | Closes a specific dropdown by ID |
| onButtonClick | (button: ButtonConfig) => void | Handles click events for action buttons (export, filter, etc.) |
| onSelectAll | () => void | Handles select all checkbox click to select/deselect all rows |
| onRowSelect | (rowId: string | number) => void | Handles individual row selection checkbox click |
| onRowToggle | (rowId: string | number) => void | Handles row expand/collapse toggle for nested rows |
| Prop | Type | Default | Description |
|---|---|---|---|
| onRowClick | (row: DataItem) => void | - | Callback function when a parent row is clicked |
| searchableColumns | string[] | - | Array of column keys to search in |
| showSearchBar | boolean | true | Whether to show the search bar |
| filterColumn | string | - | The column to filter by |
| tableTitle | string | - | Title displayed above the table |
| tableSubtitle | string | - | Subtitle displayed below the table title |
| showDarkMode | boolean | false | Whether to show dark mode toggle button |
| isDarkMode | boolean | false | Current dark mode state |
| onToggleTheme | () => void | - | Callback function to toggle between light/dark themes |
Each column object should have the following properties:
| Property | Type | Required | Description |
|---|---|---|---|
| key | string | Yes | Key to access the data in each row |
| title | string | Yes | Column header text |
| render | function | No | Custom render function for the column. Receives (value: string | number, item: DataItem) as parameters |
| filterable | boolean | No | Whether the column can be filtered |
| sortable | boolean | No | Whether the column can be sorted |
| customSortFn | function | No | Custom sorting function. Receives (rowA: DataItem, rowB: DataItem, columnId: string) as parameters |
| width | string | No | Column width (e.g., '150px', '20%') |
| minWidth | string | No | Minimum column width |
| maxWidth | string | No | Maximum column width |
| align | string | No | Text alignment ('left', 'center', 'right') |
| className | string | No | Custom CSS class for the column |
| style | object | No | Custom inline styles for the column |
You can customize the expand icon for rows with children using the expandIcon prop:
<MultiLevelTable
data={data}
columns={columns}
expandIcon={<CustomExpandIcon />} // Your custom expand icon component
/>The expand icon will be displayed for rows that have children. You can provide any React component as the icon.
The table supports row selection with the following props:
<MultiLevelTable
data={data}
columns={columns}
selectable={true} // Enable row selection
onSelectionChange={(selectedRows) => {
console.log('Selected rows:', selectedRows);
}}
/>| Prop | Type | Description |
|---|---|---|
| selectable | boolean | Enable/disable row selection functionality |
| onSelectionChange | function | Callback function that receives a Set of selected row IDs |
Note: Child rows (nested rows) do not display checkboxes. They automatically show placeholder spacers to maintain alignment with parent rows.
You can customize the sort icons for ascending and descending states:
<MultiLevelTable
data={data}
columns={columns}
sortable={true}
ascendingIcon={<CustomAscendingIcon />} // Custom icon for ascending sort
descendingIcon={<CustomDescendingIcon />} // Custom icon for descending sort
/>| Prop | Type | Description |
|---|---|---|
| ascendingIcon | ReactNode | Custom icon component for ascending sort state |
| descendingIcon | ReactNode | Custom icon component for descending sort state |
The table provides comprehensive search and filtering capabilities:
- Searchable: Enable/disable global search across all columns
- Search Input: Real-time search with debounced input
- Search Icon: Customizable search icon with proper positioning
- Placeholder Text: Customizable placeholder text for search input
- Filterable Columns: Individual columns can be marked as filterable
- Filter Dropdowns: Dropdown-based filtering with multiple selection
- Filter Options: Custom filter options for each column
- Filter State: Maintains filter state across pagination
Important Note: Search and filter features are currently implemented at the parent level only. Child rows (nested rows) are not included in search results or filter operations. This ensures consistent behavior and performance.
const columns = [
{
key: 'status',
title: 'Status',
filterable: true,
filterOptions: [
{ label: 'Active', value: 'active' },
{ label: 'Pending', value: 'pending' },
{ label: 'Completed', value: 'completed' }
]
}
];The table supports data export with customizable options:
| Prop | Type | Description |
|---|---|---|
| exportable | boolean | Enable/disable export functionality |
| exportFormats | array | Available export formats (csv, excel, json) |
| onExport | function | Custom export handler function |
<MultiLevelTable
data={data}
columns={columns}
exportable={true}
exportFormats={['csv', 'excel']}
onExport={(data, format) => {
// Custom export logic
console.log('Exporting:', data, format);
}}
/>The table supports row-level actions:
| Prop | Type | Description |
|---|---|---|
| onRowClick | function | Callback when parent row is clicked |
| onDelete | function | Callback for row deletion with confirmation |
<MultiLevelTable
data={data}
columns={columns}
onRowClick={(row) => {
console.log('Row clicked:', row);
}}
onDelete={(rowId, rowName) => {
console.log('Delete row:', rowId, rowName);
}}
/>The table component provides comprehensive pagination functionality. You can either use the default pagination or create a custom one using the pagination props:
interface PaginationProps {
page: Row<T>[]; // Current page data
canPreviousPage: boolean; // Whether previous page is available
canNextPage: boolean; // Whether next page is available
pageOptions: number[]; // Available page numbers
pageCount: number; // Total number of pages
gotoPage: (updater: number | ((pageIndex: number) => number)) => void; // Go to specific page
nextPage: () => void; // Go to next page
previousPage: () => void; // Go to previous page
setPageSize: (pageSize: number) => void; // Change page size
state: TableStateWithPagination<T>; // Current table state
}Example of custom pagination:
const CustomPagination = ({
canPreviousPage,
canNextPage,
pageOptions,
pageCount,
gotoPage,
nextPage,
previousPage,
setPageSize,
state: { pageIndex, pageSize }
}) => {
return (
<div className="pagination">
<button onClick={() => previousPage()} disabled={!canPreviousPage}>
Previous
</button>
<span>
Page{' '}
<strong>
{pageIndex + 1} of {pageOptions.length}
</strong>
</span>
<button onClick={() => nextPage()} disabled={!canNextPage}>
Next
</button>
<select
value={pageSize}
onChange={e => setPageSize(Number(e.target.value))}
>
{[10, 20, 30, 40, 50].map(size => (
<option key={size} value={size}>
Show {size}
</option>
))}
</select>
</div>
);
};
// Usage in MultiLevelTable
<MultiLevelTable
data={data}
columns={columns}
renderCustomPagination={CustomPagination}
/>The table component supports comprehensive theme customization through the theme prop. Here's the complete theme interface:
interface ThemeProps {
colors?: {
background?: string;
primaryColor?: string;
textColor?: string;
borderColor?: string;
};
table?: {
header?: {
background?: string;
textColor?: string;
borderColor?: string;
};
cell?: {
textColor?: string;
borderColor?: string;
nestedPadding?: string;
};
row?: {
levelColors?: {background: string}[];
};
filter?: {
background?: string;
textColor?: string;
borderColor?: string;
focusBorderColor?: string;
placeholderColor?: string;
};
};
pagination?: {
button?: {
background?: string;
textColor?: string;
disabledOpacity?: string;
};
select?: {
background?: string;
textColor?: string;
borderColor?: string;
};
info?: {
textColor?: string;
};
};
expandIcon?: {
color?: string;
};
}Example usage:
const theme = {
colors: {
background: '#ffffff',
primaryColor: '#1976d2',
textColor: '#333333',
borderColor: '#e0e0e0'
},
table: {
header: {
background: '#f5f5f5',
textColor: '#333333',
borderColor: '#e0e0e0'
},
cell: {
textColor: '#333333',
borderColor: '#e0e0e0',
nestedPadding: '24px'
},
row: {
levelColors: [
{ background: '#ffffff' },
{ background: '#f8f8f8' },
{ background: '#f5f5f5' }
]
},
filter: {
background: '#ffffff',
textColor: '#333333',
borderColor: '#e0e0e0',
focusBorderColor: '#1976d2',
placeholderColor: '#757575'
}
},
pagination: {
button: {
background: '#1976d2',
textColor: '#ffffff',
disabledOpacity: '0.5'
},
select: {
background: '#ffffff',
textColor: '#333333',
borderColor: '#e0e0e0'
},
info: {
textColor: '#333333'
}
},
expandIcon: {
color: '#757575'
}
};
// Usage in MultiLevelTable
<MultiLevelTable
data={data}
columns={columns}
theme={theme}
/>The theme customization allows you to:
- Global Colors: Customize background, primary, text, and border colors
- Table Components: Style headers, cells, and rows with custom colors and borders
- Nested Levels: Configure different background colors for each nesting level
- Filter Components: Customize filter dropdowns, inputs, and focus states
- Pagination: Style pagination buttons, selects, and info text
- Icons: Customize expand, sort, and action icon colors
- Responsive Design: All theme properties support responsive breakpoints
- CSS Variables: Theme properties can use CSS custom properties for dynamic theming
- Hierarchical Data: Supports unlimited nesting levels with automatic indentation
- Responsive Design: Percentage-based column widths with fixed table layout
- Performance Optimized: Virtual scrolling support for large datasets
- Accessibility: ARIA labels, keyboard navigation, and screen reader support
- Customizable Icons: Replace default expand, sort, and action icons
- Event Handling: Comprehensive callback system for all user interactions
- Level-based Styling: Different background colors for each nesting level
- Expand/Collapse: Smooth animations for row expansion and collapse
- Selection State: Visual feedback for selected rows
- Click Handlers: Support for row click and action button clicks
- Custom Rendering: Flexible cell content rendering with custom components
- Flexible Content: Support for text, numbers, custom components, and HTML
- Alignment Options: Left, center, and right text alignment
- Custom Styling: Inline styles and CSS classes for individual cells
- Icon Integration: Built-in support for expand, sort, and action icons
- Responsive Behavior: Automatic text truncation and ellipsis
- Sortable Columns: Click-to-sort functionality with custom sort icons
- Filter Integration: Dropdown filters with multi-select capability
- Custom Styling: Theme-based header styling with hover effects
- Accessibility: Proper ARIA labels and keyboard navigation
- Responsive Design: Adaptive header layout for mobile devices
- Page Navigation: Previous/next buttons with page number display
- Page Size Selection: Dropdown to change items per page
- Custom Rendering: Complete pagination component replacement
- State Management: Automatic page state handling
- Responsive Layout: Mobile-friendly pagination controls
- Dropdown Filters: Multi-select dropdown with search capability
- Global Search: Real-time search across all columns
- Filter State: Persistent filter state across pagination
- Custom Options: Configurable filter options per column
- Outside Click: Automatic dropdown closure on outside clicks
- Multiple Formats: CSV, Excel, and JSON export support
- Custom Handlers: Flexible export function customization
- Data Filtering: Export only visible or selected data
- Progress Feedback: Export progress indicators
- Error Handling: Comprehensive error handling for export operations
src/App.tsx- A demo component that showcases the MultiLevelTable with sample datasrc/main.tsx- The entry point for the development environmentsrc/index.css- Basic styling for the table componentsrc/components/- All table components (MultiLevelTable, TableRow, TableCell, etc.)src/styles/- CSS files for styling individual componentssrc/types/- TypeScript type definitionssrc/constants/- Theme and configuration constantsexample/- Complete example application with all features
# Start the development server
npm run dev
# Build the package
npm run build
# Run linting
npm run lint- Hot Module Replacement (HMR): Instant feedback during development
- TypeScript Support: Full type checking and IntelliSense support
- ESLint Configuration: Code quality and consistency enforcement
- Sample Data: Comprehensive test data with nested structures
- Component Testing: Unit tests for all major components
- Responsive Design: Mobile-first responsive design patterns
- Accessibility: ARIA labels and keyboard navigation support
- Performance: Optimized rendering with React.memo and useMemo
Here's a complete example showing how to use the component with all features enabled:
import React from 'react';
import { MultiLevelTable } from '@keyvaluesystems/multilevel-table';
function App() {
const data = [
{
id: 1,
name: 'Parent 1',
value: 100,
status: 'active',
children: [
{
id: 2,
name: 'Child 1',
value: 50,
status: 'pending',
},
{
id: 3,
name: 'Child 2',
value: 50,
status: 'completed',
},
],
},
];
const columns = [
{
key: 'name',
title: 'Name',
filterable: true,
},
{
key: 'value',
title: 'Value',
filterable: true,
render: (value) => `$${value}`,
},
{
key: 'status',
title: 'Status',
filterable: true,
render: (value) => (
<span style={{
padding: '4px 8px',
borderRadius: '4px',
backgroundColor: value === 'active' ? '#e6ffe6' :
value === 'pending' ? '#fff3e6' : '#e6f3ff',
color: value === 'active' ? '#006600' :
value === 'pending' ? '#cc7700' : '#0066cc'
}}>
{value}
</span>
),
},
];
const theme = {
colors: {
background: '#ffffff',
primaryColor: '#1976d2',
textColor: '#333333',
borderColor: '#e0e0e0'
},
table: {
header: {
background: '#f5f5f5',
textColor: '#333333',
borderColor: '#e0e0e0'
},
cell: {
textColor: '#333333',
borderColor: '#e0e0e0'
},
row: {
levelColors: [
{ background: '#ffffff' },
{ background: '#f8f8f8' },
{ background: '#f5f5f5' }
]
}
}
};
return (
<div>
<MultiLevelTable
data={data}
columns={columns}
pageSize={10}
theme={theme}
sortable={true}
selectable={true}
searchable={true}
filterable={true}
exportable={true}
onSelectionChange={(selectedRows) => {
console.log('Selected rows:', selectedRows);
}}
onRowClick={(row) => {
console.log('Row clicked:', row);
}}
onDelete={(rowId, rowName) => {
console.log('Delete row:', rowId, rowName);
}}
/>
</div>
);
}
export default App;MIT