Migration Guide: v2.4.1

This guide will help you migrate from v2.4.0 to v2.4.1, which introduces enhanced column editor features, a unified icons API, and some breaking changes.

What's New in v2.4.1

  • Drag & Drop Column Reordering - Reorder columns directly in the column editor
  • Column Search - Built-in search functionality in the column editor
  • Unified Icons API - New icons prop for cleaner icon configuration
  • Enhanced Column Editor Config - New columnEditorConfig prop with comprehensive options

Breaking Changes

Removed: columnEditorPosition

The columnEditorPosition prop has been removed. The column editor now uses an optimized default position.

❌ Before (v2.4.0):

React TSX
1<SimpleTable
2  editColumns={true}
3  columnEditorPosition="right"
4  // ... other props
5/>

✅ After (v2.4.1):

React TSX
1<SimpleTable
2  editColumns={true}
3  // columnEditorPosition removed - uses optimized default
4  // ... other props
5/>

Deprecated Props (Still Work, But Update Recommended)

The following props are deprecated and will show console warnings in development mode. They still work in v2.4.1 but will be removed in a future version.

1. columnEditorText → columnEditorConfig

The columnEditorText prop is now part of the more comprehensive columnEditorConfig object.

❌ Before (Deprecated):

React TSX
1<SimpleTable
2  editColumns={true}
3  columnEditorText="Customize Columns"
4  // ... other props
5/>

✅ After (v2.4.1):

React TSX
1<SimpleTable
2  editColumns={true}
3  columnEditorConfig={{
4    text: "Customize Columns",
5    searchEnabled: true,                    // NEW: Enable search (default: true)
6    searchPlaceholder: "Search columns...", // NEW: Custom placeholder
7  }}
8  // ... other props
9/>

2. Individual Icon Props → icons Object

All individual icon props have been consolidated into a single icons object for better organization.

Deprecated props: expandIcon, filterIcon, headerCollapseIcon, headerExpandIcon, nextIcon, prevIcon, sortDownIcon, sortUpIcon

❌ Before (Deprecated):

React TSX
1import { FontAwesomeIcon } from "@fortawesome/react-fontawesome";
2import { 
3  faChevronRight, 
4  faFilter, 
5  faCaretUp, 
6  faCaretDown,
7  faAngleLeft,
8  faAngleRight,
9  faChevronDown
10} from "@fortawesome/free-solid-svg-icons";
11

12<SimpleTable
13  expandIcon={<FontAwesomeIcon icon={faChevronRight} />}
14  filterIcon={<FontAwesomeIcon icon={faFilter} />}
15  sortUpIcon={<FontAwesomeIcon icon={faCaretUp} />}
16  sortDownIcon={<FontAwesomeIcon icon={faCaretDown} />}
17  nextIcon={<FontAwesomeIcon icon={faAngleRight} />}
18  prevIcon={<FontAwesomeIcon icon={faAngleLeft} />}
19  headerExpandIcon={<FontAwesomeIcon icon={faChevronRight} />}
20  headerCollapseIcon={<FontAwesomeIcon icon={faChevronDown} />}
21  // ... other props
22/>

✅ After (v2.4.1):

React TSX
1import { FontAwesomeIcon } from "@fortawesome/react-fontawesome";
2import { 
3  faChevronRight, 
4  faFilter, 
5  faCaretUp, 
6  faCaretDown,
7  faAngleLeft,
8  faAngleRight,
9  faChevronDown,
10  faGripVertical // NEW: For drag handle
11} from "@fortawesome/free-solid-svg-icons";
12

13<SimpleTable
14  icons={{
15    expand: <FontAwesomeIcon icon={faChevronRight} />,
16    filter: <FontAwesomeIcon icon={faFilter} />,
17    sortUp: <FontAwesomeIcon icon={faCaretUp} />,
18    sortDown: <FontAwesomeIcon icon={faCaretDown} />,
19    next: <FontAwesomeIcon icon={faAngleRight} />,
20    prev: <FontAwesomeIcon icon={faAngleLeft} />,
21    headerExpand: <FontAwesomeIcon icon={faChevronRight} />,
22    headerCollapse: <FontAwesomeIcon icon={faChevronDown} />,
23    drag: <FontAwesomeIcon icon={faGripVertical} />, // NEW!
24  }}
25  // ... other props
26/>

New Features

Column Search in Editor

The column editor now includes built-in search functionality. Users can quickly find columns by typing in the search box.

React TSX
1<SimpleTable
2  editColumns={true}
3  columnEditorConfig={{
4    text: "Columns",
5    searchEnabled: true,                      // Enable search (default: true)
6    searchPlaceholder: "Find a column...",    // Custom placeholder
7    searchFunction: (header, searchTerm) => { // Optional: custom search logic
8      return header.label.toLowerCase().includes(searchTerm.toLowerCase());
9    }
10  }}
11  // ... other props
12/>

Learn more in the Column Editing documentation.

Drag & Drop Column Reordering

Users can now reorder columns by dragging them within the column editor. This works alongside the existing header drag-and-drop functionality.

No configuration needed! Drag-and-drop in the column editor is automatically enabled when editColumns=.

Custom Drag Icon

Customize the drag handle icon in the column editor using the new icons.drag property.

React TSX
1import { FontAwesomeIcon } from "@fortawesome/react-fontawesome";
2import { faGripVertical } from "@fortawesome/free-solid-svg-icons";
3

4<SimpleTable
5  editColumns={true}
6  icons={{
7    drag: <FontAwesomeIcon icon={faGripVertical} className="text-gray-500" />,
8  }}
9  // ... other props
10/>

Complete Migration Example

Here's a complete before and after example showing all the changes:

❌ Before (v2.4.0):

React TSX
1import { SimpleTable } from "simple-table-core";
2import { FontAwesomeIcon } from "@fortawesome/react-fontawesome";
3import { 
4  faChevronRight, 
5  faFilter, 
6  faCaretUp, 
7  faCaretDown 
8} from "@fortawesome/free-solid-svg-icons";
9

10<SimpleTable
11  defaultHeaders={headers}
12  rows={data}
13  editColumns={true}
14  columnEditorText="Customize Columns"
15  columnEditorPosition="right"
16  expandIcon={<FontAwesomeIcon icon={faChevronRight} />}
17  filterIcon={<FontAwesomeIcon icon={faFilter} />}
18  sortUpIcon={<FontAwesomeIcon icon={faCaretUp} />}
19  sortDownIcon={<FontAwesomeIcon icon={faCaretDown} />}
20/>

✅ After (v2.4.1):

React TSX
1import { SimpleTable } from "simple-table-core";
2import { FontAwesomeIcon } from "@fortawesome/react-fontawesome";
3import { 
4  faChevronRight, 
5  faFilter, 
6  faCaretUp, 
7  faCaretDown,
8  faGripVertical
9} from "@fortawesome/free-solid-svg-icons";
10

11<SimpleTable
12  defaultHeaders={headers}
13  rows={data}
14  editColumns={true}
15  columnEditorConfig={{
16    text: "Customize Columns",
17    searchEnabled: true,
18    searchPlaceholder: "Search columns...",
19  }}
20  icons={{
21    expand: <FontAwesomeIcon icon={faChevronRight} />,
22    filter: <FontAwesomeIcon icon={faFilter} />,
23    sortUp: <FontAwesomeIcon icon={faCaretUp} />,
24    sortDown: <FontAwesomeIcon icon={faCaretDown} />,
25    drag: <FontAwesomeIcon icon={faGripVertical} />,
26  }}
27/>

New CSS Classes and Variables

If you're using custom CSS, you can now style the new column editor features:

New CSS Classes:

  • .st-column-editor-search-wrapper - Search input container
  • .st-column-editor-search - Search input wrapper
  • .st-column-editor-list - Column list container
  • .st-column-label-container - Column label wrapper
  • .st-drag-icon-container - Drag handle container
  • .st-column-editor-drag-separator - Drag drop indicator line

New CSS Variables:

  • --st-drag-separator-color - Color of the drag drop indicator (theme-specific)

Learn more in the Custom Theme documentation.

Migration Checklist

  • ☐Remove columnEditorPosition prop
  • ☐Replace columnEditorText with columnEditorConfig
  • ☐Consolidate individual icon props into icons object
  • ☐Test column editor search functionality
  • ☐Test drag-and-drop column reordering in column editor
  • ☐Update custom CSS if using column editor styles

Need Help?

If you encounter any issues during migration, check out these resources: