Migrate from ngx-sortablejs to ng-hub-ui-sortable
ngx-sortablejs has not had a release since December 2020. This guide maps its directive, inputs and outputs to ng-hub-ui-sortable, shows a list before and after, and says what changes at runtime. The new names were checked against the library source and the old ones against the published 11.1.0 package.
1 · Why move
The last release of ngx-sortablejs, 11.1.0, came out on 25 December 2020. It declares Angular 11 as its peer dependency and is published in the pre-Ivy (View Engine) format, which Angular stopped supporting in version 16, so a current Angular application cannot build it.
If all you need is the same template API on a current Angular, a maintained fork exists: @worktile/ngx-sortablejs, whose 22.0.0 came out in September 2026 for Angular 22. It keeps the selector, input and output names, so only the import changes. Moving to ng-hub-ui-sortable is the better fit when you also want signal inputs, real outputs and the other additions below, at the cost of rewriting every template that uses the directive.
ng-hub-ui-sortable is a fork of that fork. It is a standalone directive with signal inputs, one input per SortableJS option, outputs for the SortableJS callbacks, an autoUpdateArray switch, array helpers, keyboard reordering and a provideSortable() provider. It needs Angular 17.3 or newer.
2 · Install and import
Replace the package and register the directive. Global options move from SortablejsModule.forRoot() to provideSortable(), and the directive is imported by the components that use it.
Before
After
sortablejs is now installed by the package itself. Keep @types/sortablejs in your project: the library re-exports the SortableJS types and does not ship them.
3 · API mapping
Every public member of ngx-sortablejs 11.1.0, and what replaces it.
| Before | After | Notes |
|---|---|---|
SortablejsModule, SortablejsModule.forRoot(options) | SortableDirective, provideSortable(options) | The directive is standalone. SortableModule and SortableModule.forRoot(options) still exist but are deprecated; forRoot still requires its argument. |
[sortablejs]="items" | [hubSortable]="items" | Renamed. Accepts a plain array, a FormArray or a WritableSignal holding an array. |
[sortablejsOptions] | [options] | Still the whole SortableJS options object. The 32 individual inputs (for example [group], [handle], [animation]) override the same key inside it. |
[sortablejsContainer] | [container] | Renamed. It is still resolved once at initialization; a selector that matches nothing leaves the directive inactive without an error. |
[sortablejsCloneFunction] | [cloneFunction] | Renamed, same signature. Only consulted for clone drags with an array bound and autoUpdateArray on. |
(sortablejsInit) | (init) | Same Sortable instance, now typed. It fires after the next render, not after a timeout, and never on the server. |
onStart, onEnd, onAdd, onUpdate, onSort, onRemove, onFilter, onChange, onChoose, onUnchoose, onClone | (start), (end), (add), (update), (sortEvent), (remove), (filterEvent), (change), (choose), (unchoose), (clone) | Callbacks inside [options] keep working. The outputs are new. sort and filter carry the suffix Event because those names are inputs. |
onMove | onMove in [options], (move) | A veto from onMove in [options] still works. The (move) output only observes: an Angular output cannot return false. |
SortablejsDirective | SortableDirective | Every input is a signal input, so reads become calls (options()) and writes are not possible. |
SortableData | SortableData | Same name, widened to accept a WritableSignal. |
GLOBALS, SortablejsService | No equivalent | Not exported. The package root exposes only the directive, the module, the array helpers, provideSortable, the bindings classes and the types. |
SortablejsBindings, SortablejsBinding | SortableBindings, SortableBinding | Now exported from the package root (they needed a deep import before). |
| — | [autoUpdateArray], [keyboardSorting], [keyboardMessages], moveItemInArray(), transferArrayItem(), copyArrayItem() | New: autoUpdateArray, keyboardSorting, keyboardMessages, and the array helpers moveItemInArray, transferArrayItem and copyArrayItem, whose edge cases differ slightly from the CDK ones. |
4 · A typical usage, before and after
A sortable task list with a drag handle, first with ngx-sortablejs and then with ng-hub-ui-sortable.
Before
After
5 · Behaviour differences to check
These are the differences most likely to surprise you after the rename.
- There is no codemod, and a plain find and replace on sortablejs corrupts the longer attribute names. Replace sortablejsOptions, sortablejsContainer and sortablejsCloneFunction first, then the bare directive.
- Options merge in three layers: global options, then [options], then the individual inputs. [options]="{ animation: 150 }" together with [animation]="0" gives 0, with no warning. Use one style per element.
- Do not move drop validation from options.onMove to the (move) output. The output cannot cancel a move, so every forbidden drop would be accepted.
- A callback in [options] and the matching output on the same element both run, so a handler wired to both runs twice per event. Pick one channel per event.
- Names such as (change), (start), (end), (add), (remove) and (update) on the host element now bind to the directive outputs, not to DOM events. Treat each existing binding as a rewrite, and move native listeners to a wrapper element.
- The instance is created outside the Angular zone, so callbacks that are not wrapped by the directive (plugin callbacks, setData, store) do not trigger change detection by themselves. Write a signal or mark the view yourself.
- The new inputs have no prefix, so a static attribute such as draggable="false" on the host is passed to the draggable option as the string "false", and nothing becomes draggable. Put the directive on a wrapper if an attribute collides.
- Keyboard reordering is on by default: every item (or its handle) becomes a Tab stop, Enter or Space picks it up, arrows move it. Set [keyboardSorting]="false" if you do not want it.
6 · Documentation
The full reference for the directive, with live examples, is on its documentation page: ng-hub-ui-sortable documentation