Support and upgrades
2.0 breaking changes
Each breaking change from 1.3 to 2.0 with the 1.3 form, the 2.0 form, and the change to make in your code.
Each row is one Breaking: entry of the changelog. Add-on breaking changes lists the import, export, find and replace, and presence rows. Migrate to 2.0 gives the order of the steps.
| Area | Rows |
|---|---|
| Sorting and filtering | Sorts, filters |
| Selection and row actions | Checked rows |
| Editing and validation | Gates, validation |
| Columns and styling | Pins, widths, locale |
| Keyboard | Keys, shortcuts |
| Server data and pagination | Scroll rows, pagers |
| Exports and labels | Barrels, labels |
Sorting and filtering
| Change | 1.3 | 2.0 | What to change |
|---|---|---|---|
| Text sort language | The runtime language | locale, then "en-US". sortLocale overrides it. | Pass locale or sortLocale. A custom text compare calls sortCollator().compare. |
text, longText, and url order | localeCompare: item10 before item2 | Numeric and case-insensitive: item2 before item10 | Set sortCompare to localeCompare. |
| Sort, filter, and search callbacks | Fire before the write. A throw stops the write. | Fire after the write. A throw keeps the write. | Keep your own copy of the old value. |
FilterOperator | A closed union | A built-in operator or any string | Give a switch a default branch. BuiltInFilterOperator is the closed set. |
| Column filter keys | filterOperators, filterMatch | filter: { operators, match } | Move the keys into filter. |
| Filtered empty grid | labels.grid.emptyState ("No rows") | labels.grid.noResults ("No results") | To keep "No rows", set labels.grid.noResults. |
operatorsForColumn | A DataGridFilterMenu prop | Removed | Set filter.operators on the column. |
toggleSort | toggleSort(id, true) | toggleSort(id, { additive: true }) | Pass an options object. |
| Sort or filter on an unknown column | A filter matches no row | Dropped | Fix the column id. |
| Equal sort or filter spec | Fires the callback | No callback | Refetch yourself. |
| Set operators with a custom match | With filterMatch, a text or untyped column drops the set operators and the header filter. | Every column keeps them, and the built-in match runs them. | To run your match for them, list isAnyOf and isNoneOf in filter.operators. |
viewIndex of a grouped grid | Holds data indexes only | Holds an entry below 0 for each group row. rowIdAtViewRow answers the group id. | Read a row through dataIndexAt. A grid without groupBy is unchanged. |
Selection and row actions
| Change | 1.3 | 2.0 | What to change |
|---|---|---|---|
| Checked row memory | keepCheckedRows, keepHiddenCheckedRows | checkedRowsLifetime | Map the props with the table below. |
| Checkbox state | A cell range, such as Ctrl+A, checks the markers. | The checkboxes, aria-selected, and the count read the checked rows. Ctrl+A selects cells. | Call setAllRowsChecked(true) to check every row. |
| Row action arguments | deleteRows([4]), duplicateRows([4]), deleteRowsById(ids), setRowSelected(4, true), setAllRowsSelected | deleteRowsAt([4]), duplicateRowsAt([4]), deleteRows(ids), setRowCheckedAt(4, true), setAllRowsChecked | Rename the calls. setRowChecked(rowId, checked) takes a row id. |
| Row actions over unloaded rows | Run over the holes | Do nothing in a scroll-mode grid | Delete known rows with deleteRows(ids). |
enableRowReorder | Turns off the row drag | Removed. A reorder family rowMarkers mode arms the drag. | Use a plain mode, such as rowMarkers="checkbox". |
| Checked rows with a checkbox marker | 'until-click' | 'until-cleared' | Set checkedRowsLifetime="until-click". |
Header click with totalRowCount | Selects the column | Sorts | Set headerClickBehavior="select". |
selectAllMatching() | Returns nothing, warns without totalRowCount | Returns { ok, reason }, works on client grids | Read the result instead of the warning. |
Row move under sortMode="server" with a sort | Moves the loaded rows | Does nothing, reason "view-ordered" | Clear the sort before a move. |
The props of 1.3 map to checkedRowsLifetime like this:
| 1.3 props | 2.0 prop |
|---|---|
| neither | the default: 'until-click', or 'across-filters' with totalRowCount |
keepCheckedRows | checkedRowsLifetime="until-cleared" |
keepCheckedRows and keepHiddenCheckedRows | checkedRowsLifetime="across-filters" |
keepHiddenCheckedRows alone | Delete it. It had no effect. |
Editing and validation
| Change | 1.3 | 2.0 | What to change |
|---|---|---|---|
| Callback errors | Callbacks rethrow | A throw goes to reportError | Catch in the callback. |
updateCells source | Defaults to "stream" | Required | Pass { source: "stream" }. |
| Second insert or delete | Ignored, "gate-pending" | Aborts the pending one | Drop that check. |
| Two plugins, one command name | The later plugin wins | The first plugin keeps it | Order the plugins, or define the command in commands. |
| Edit gate | onEditStart(cell) | onBeforeEditStart(cell, { signal }) | Rename the prop. |
| Soft validation | onInvalid: "warn" | validationMode: "warn" | Rename the column option. |
Bulk writes on "warn" columns | Paste, fill, and import drop invalid values | They keep the values and flag them in cellErrors | To drop them, use "block" or processPaste. |
| Delete and Cut | Empties a required cell | Run validate on the empty value under "block" | To allow it, accept the empty value in validate. |
| Number text | abc clears the cell. 1,234 stores 1.234. | The cell keeps its value, and the grid reports the text. | Clean the text before a paste or an import. |
| Select text | Text that matches no choice empties the cell | The cell keeps its value, and the grid reports the text | To empty the cell, return null for the text from processCellFromClipboard. |
CellEditorProps | onChange(value) then commit(movement) | Also commitValue(value, movement) | Pass commitValue where you build editor props yourself, such as a test. |
Column validate with a type validate | The column rule replaces the type rule | The type rule runs first, then the column rule | To allow longer longText, raise options.maxLength. |
Column locale without a format | No effect | Grouped digits for number, the medium date style for date | To keep the raw display, remove locale. |
| Fill gate | onFill({ target, preventDefault }) | processFill({ target, cells }) returns the cells or false | Return false to cancel. Return cells to write. |
pasteFromClipboard result | "empty" for a paste that does not start | "refused". "empty" means no text. | Handle "refused". |
cut() result | Clears the cells while an editor is open | "refused" while an editor is open | Handle "refused". |
| Cut source | source: "delete" | source: "cut" | Check "cut" next to "delete". Add it to a custom recordSources. |
sanitizeClipboardFormulas | Default false: a copy keeps =SUM(A1) | Default true: a copy writes '=SUM(A1) | To copy raw text, set sanitizeClipboardFormulas={false}. |
| Clipboard failure labels | pasteBlocked and clipboardFailed are strings | A string or a function of the modifier name | Handle both forms where you read them. |
canUndo, canRedo | true on a readOnly grid with entries | false while readOnly | Delete a readOnly || guard. |
DataGridApi writes | api.startEditing, api.stopEditing, api.setSelection | api.actions.startEditing, api.actions.cancelEditing, api.actions.setSelection | Call the writes through api.actions. |
Columns and styling
| Change | 1.3 | 2.0 | What to change |
|---|---|---|---|
| Pin values | "left", "right", pin-left, data-pinned="left" | "start", "end", pin-start, data-pinned="start" | Rename. Saved layouts with the old values still load. |
| Pin shadow hooks | data-grid-pin-shadow="left", data-scrolled-left, --grid-pin-shadow-left-x | "start", data-scrolled-start, --grid-pin-shadow-start-x, and the end forms | Rename the CSS selectors. |
Def pin and hidden | Each columns array applies them again | They apply at the first appearance of the column id. A later change warns in development. | Use setColumnPin, setColumnHidden, or columnLayout. |
| Width actions | setColumnWidth (drag write), commitColumnWidth | previewColumnWidth (drag write), setColumnWidth (commit) | Rename both calls. |
| Cell alignment | align: "left" | "right" | "center", <CellSpan align> | align: "start" | "center" | "end". CellSpan inherits it. | Use the logical values. Delete the CellSpan prop. |
| Node header sort arrow | A node header draws no arrow of its own | Every header shows the arrow while its column is sorted | Set sortIndicator: false on the column, or remove the DataGridSortIndicator in the header. |
Cell z-index | An unpinned cell has none, so a z-* class stacks it | Every body cell has an integer z-index | Render content that covers other cells in a portal. |
text placeholder | An option that nothing read | Removed. longText keeps it. | Delete it from text columns. |
| Number and date language | options.locale on each column, status bar locale | locale on DataGrid or DataGridProvider | Set locale once on the grid. |
Keyboard
| Change | 1.3 | 2.0 | What to change |
|---|---|---|---|
| Add-on actions | undo, redo, fillDown, fillRight, openFind, openFindReplace in the core | Each add-on declares and binds its own actions | For your own command, declare the name. |
commitDown and siblings | Keymap names that change no key | Removed | Delete them from keymap. |
| Default chords | toggleAllRows: mod+shift+e. openFindReplace: ctrl+h. | mod+shift+Enter and shift+alt+Enter | To keep an old chord, bind it in keymap. |
DataGridGlobalShortcuts flags | A flag replaces the default set | A flag adds to undo and redo | For select all alone, add undo={false} redo={false}. |
DataGridGlobalShortcuts bare key | Fires page-wide | Needs Ctrl or Cmd | Add a keydown listener. |
captureFindShortcut | A DataGridSearch prop | The focusSearch keymap action | Write keymap={{ focusSearch: [] }} to leave Mod+F to the browser. |
| Shortcuts dialog | DataGridKeybindingsShortcut and your dialog state | useDataGridKeybindings() returns { plugin, open, close } | Pass plugins={[keys.plugin]}. Call keys.open() from a button. |
Server data and pagination
| Change | 1.3 | 2.0 | What to change |
|---|---|---|---|
| Scroll rows | useDataGridLazyRows, DataGridLazyGuard | useDataGridServerRows({ mode: "scroll" }) | Follow Move the lazy rows. |
| Row range type | Range from data-grid-lazy | RowRange from data-grid | Rename the import. |
| Block request start | At once | After loadDelayMs (100 ms) | For the 1.3 timing, pass loadDelayMs: 0. |
| Loaded rows | Every row stays | At most maxLoadedRows (10,000) | To keep every row, pass maxLoadedRows: Infinity. |
| Stream batch size | No limit | 100,000 patches. The rest skip as "limit". | Split a bigger batch. |
| Stream writes | Skip read-only grids, columns, and rows | Write into read-only columns and rows. A call without source is a stream call, but a readOnly grid refuses it. | Pass source: "edit" to keep the checks. |
reshapeDelayMs of useDataGridServerRows | Off unless set | 1000 while the spec has a sort or a filter | Pass reshapeDelayMs: false. |
| Server pages | useDataGridPagination server mode | useDataGridServerPager | Move the call. Its options type is UseDataGridServerPagerOptions. |
| Pagination result | { pageData, controls }, total, reconcilePage | { pageData, pager }, totalRowCount, a pager that clamps | Rename. Spread pager into DataGridPaginationBar. |
| URL state parts | Sort, filters, and search text | Sort only | To keep filters and search text in the URL, pass spec={["sort", "filter", "search"]}. |
| URL page size | 25 | The first of pageSizeOptions (10) | To keep 25, pass defaultPageSize: 25. |
| URL pagination count | The total option | No count option. The pager clamps. | Delete total. |
fetchRows of the query layer | Resolves RowsAnswer | Resolves `RowsAnswer | GroupsAnswer` |
Exports and labels
| Change | 1.3 | 2.0 | What to change |
|---|---|---|---|
data-grid barrel | Twelve hooks and helpers | Removed from the barrel | Use the replacements. |
| Toolbar, io, and keybindings helpers | Exported | Removed from the barrels | Removed exports lists the names. |
| Pinned row components | DataGridPinnedRow, DataGridPinnedRowBand in the barrel | Module files only | Let useDataGridPinnedRows render them. |
undefined label | Removes the label | Keeps the default | Set "" to blank a string label. |
| Right-click on a blank area | No menu | The browser menu | Nothing. |
Related
Migrate to 2.0
Move a grid from 1.3 to 2.0. Replace the lazy rows add-on with server rows, apply each breaking change, and check the changed behavior.
2.0 add-on breaking changes
Each import, export, find and replace, and presence breaking change from 1.3 to 2.0 with the 1.3 form, the 2.0 form, and the change to make.