Migration Guide to 9.x (2025-05-10)
Last updated
Last updated
This new release is focused around 2 things, we now ship ESM-only builds (in other words, CommonJS builds are fully dropped and only ESM will remain), this move will cut the npm download size by half. The other big change is an internal one which is an organizational one, I'm moving all framework wrappers directly into Slickgrid-Universal (Angular, Aurelia, React and Vue wrappers are now all located under the folder), this will help tremendously with the project maintenance (any new PR will now run against all frameworks all at once (catching bugs early), publishing a new version is becoming a single execution for all frameworks all at once, and finally having a single codebase to test & troubleshoot any wrapper, etc... will be so much easier to handle). Now Slickgrid-Universal name totally makes sense with this new structure change. 🌐
Wait, what happened to version 6 to 8?
I'm skipping versions 6-8 and going straight to v9.0 because some of the wrappers (Angular-Slickgrid, Aurelia-Slickgrid) were already at v8.x and so the next available major version bump for everyone is v9.0
The other great thing about having everything under the same roof/project is that every package will be released at the exact same time with the exact same versions across the board. Everything will be released under v9.0 and whenever a new feature/bugfix comes in, then every package will be bumped to v9.1 and so on (no more version discrepancies).
Major Changes - Quick Summary
minimum requirements bump
Node v20+
upgrade Vanilla-Calendar-Pro to v3 with
skipping v6-8 and going straight to v9.0
now using clipboard
API, used in ExcelCopyBuffer/ContextMenu/CellCopy, which might requires end user permissions
removing Arrow pointer from Custom Tooltip addon (because it was often offset with the cell text)
Note: if you come from an earlier version, please make sure to follow each migrations in their respected order (review previous migration guides)
colspanCallback
was deprecated and removed, please use the globalItemMetadataProvider
instead
Row Detail changes
itemDetail
property is removed, just use item
(there's no reason to keep duplicate props)
parent
property renamed to parentRef
OnRowBackToViewportRangeArgs
and OnRowOutOfViewportRangeArgs
were equal, so it was merged into a new OnRowBackOrOutOfViewportRangeArgs
interface
Draggable Grouping setDroppedGroups
to load grid with initial Groups was deprecated and now removed, simply use initialGroupBy
instead
for Header Menu, we had 2 similar events onHeaderMenuHideColumns
and onHideColumns
that were doing basically the same thing, so I decided to drop onHeaderMenuHideColumns
rowTopOffsetRenderType
default is changing from 'top'
to 'transform'
and the reason is because transform
is known to have better styling perf, especially on large dataset, and that is also what Ag-Grid uses by default.
rowTopOffsetRenderType: 'top'
rowTopOffsetRenderType: 'transform'
if you are using Cypress to get the row X in the grid, which is what we do ourselves, then you will need to adjust your tests
cy.get([style="top: ${GRID_ROW_HEIGHT * 0}px;"])
cy.get([style="transform: translateY(${GRID_ROW_HEIGHT * 0}px);"])
OR cy.get([data-row=0])
Please note that you will have to change the default to
rowTopOffsetRenderType: 'top'
when using either RowSpan and/or Row Detail features.
Vanilla-Calendar-Pro was upgraded to v3.0 and the main breaking change is that they migrated to flat config (instead of complex object config) and this mean that if you use any of their option, then you'll have to update them to be flat.
The biggest change that you will most probably have to update is the min/max date setting when using the 'today'
shortcut as shown below:
The GridService
has CRUD methods that were sometime returning a single item and other times an array of items and for that reason we had to rely on code like onItemAdded.subscribe(item => { const items = Array.isArray(item) ? item : [item] }
. So for that reason, I decided to change the event names to plural and always return an array of items which is a lot more predictable.
onItemAdded
renamed to onItemsAdded
onItemDeleted
renamed to onItemsDeleted
onItemUpdated
renamed to onItemsUpdated
onItemUpserted
renamed to onItemsUpserted
You can start using new properties and options shown below in v9.0 and above.
So when I created the project, I used a few TypeScript Enums and I though this was great but it turns out that all of these Enums end up in the final transpiled JS bundle. So in the next major, I'm planning to remove most of these Enums and replace them with string literal types (type
instead of enum
). So you should consider using string types as much and as soon as possible in all your new grids. Note that at the moment, they are only deprecations, and will only be dropped in the future (not now, but you should still consider this for the future), for example:
Note that migrating from
FieldType
to string types was already doable for the past couple years, so this one is far from new.
Below are a list of Enums being deprecated and you should think about migrating them eventually because they will be removed in the next major release (whenever that happens, but that won't be before another year). Note that the list below are only a summary of these deprecations and replacements.
Enum Name
from enum
to string type
Note
FileType
FieldType.boolean
'boolean'
FileType.number
'number'
-
-
-
FieldType
FileType.csv
'csv'
FileType.xlsx
'xlsx'
-
-
-
GridStateType
GridStateType.columns
'columns'
GridStateType.filters
'filters'
GridStateType.sorters
'sorters'
-
-
-
Operator
Operator.greaterThan
'>'
Operator.lessThanOrEqual
'<='
Operator.contains
'Contains'
or 'CONTAINS'
Operators are written as PascalCase
Operator.equal
'EQ'
Operator.rangeExclusive
'RangeExclusive'
-
-
-
SortDirection
SortDirection.ASC
'ASC'
or 'asc'
SortDirection.DESC
'DESC'
or 'desc'
-
-
-
deprecating editorOptions
and filterOptions
, they are being renamed as options
in order to make it easier to merge and simplify editor/filter options, I'm merging them into a single options
property which will make it more easily transportable (you will be able to reuse the same options
for both the editor/filter if need be). You can start using options
in v9.0 and above.
[!NOTE] for a complete list of option changes, visit the Vanilla-Calendar-Pro page, which details every single options with their new option names.
See list for all available opeators