A typed Blazor wrapper for SortableJS 1.15.7. The pinned bundle is a static web asset and is registered automatically: no npm install, CDN, or script tag is required.
Live storybook - interactive stories for every feature.
dotnet add package Kebechet.Blazor.SortableJSThe bound IList<T> is reordered in place. Item objects are never serialized through JavaScript, so their reference identity is preserved.
@usingKebechet.Blazor.SortableJS
<SortableItems="_exercises"Context="exercise"Options="_options"ItemClass="exercise-card">
<ItemTemplate>@exercise.Name</ItemTemplate>
</Sortable>
@code{privatereadonlyList<Exercise> _exercises=new()
{
new("Squat"),
new("Bench press"),
new("Deadlift")
};
privatereadonlySortableOptions_options=new()
{
AnimationDuration=150,
GhostClass="drag-ghost"
};
privatesealedrecordExercise(stringName);
}Connected and nested lists only need the same group name. Each component registers itself automatically, regardless of nesting depth.
<SortableItems="_backlog"Options="_connected"Context="item">
<ItemTemplate>@item</ItemTemplate>
</Sortable>
<SortableItems="_done"Options="_connected"Context="item">
<ItemTemplate>@item</ItemTemplate>
</Sortable>
@code{privatereadonlyList<string> _backlog=new() { "Design", "Implement" };
privatereadonlyList<string> _done=new() { "Verify" };
privatereadonlySortableOptions_connected=new()
{
Group=newSortableGroupOptions
{
Name="work",
PullMode=PullMode.Enabled,
PutMode=PutMode.Enabled
}
};
}Use CloneFunction to create a distinct object for clone mode, or TryConvertFunction on a destination whose item type differs from the source - returning false refuses the item and leaves both collections untouched, so a rejection does not have to be an exception. ShouldUseItemKeys is enabled by default; set ItemKeySelector when the item itself is not the desired stable key.
Items may be null, which makes the list accept-only: it takes drops and raises the usual callbacks but stores nothing, and items still leave their source collection. That is a delete or archive zone without a throwaway list behind it. IsItemDraggable marks individual rows undraggable without hand-rolling a marker class and filter selector.
Register them so they are scoped like any other service:
builder.Services.AddSortableJs(options =>options.AnimationDuration=150);SortableDefaults.Options still works and is fine to assign once at startup. Avoid it on Blazor Server for anything user-specific: the static is shared by every circuit, so a per-user or per-tenant default would change behaviour for everyone connected. A registered ISortableDefaults takes precedence.
All fifteen callbacks use SortableEventArgs<TItem>. OnAdd runs before collection mutation, while the moved reference is still in the source; OnRemove follows. OldIndexes and NewIndexes contain every affected index for MultiDrag, not only the primary item.
They are observational. SortableJS reads the return value of onMove, group.pull and group.put synchronously, and an EventCallback is asynchronous, so OnMove cannot veto a drop or steer placement. Three separate parameters do that:
<SortableItems="_items"MoveDecision="context => context.RelatedItem?.IsPinned == true?SortableMoveDecision.Reject:SortableMoveDecision.Default"
CanAcceptItem="context => context.Item?.IsArchived == false"/>MoveDecision can reject a move or force insertion before or after the item under the pointer; CanAcceptItem and CanReleaseItem are the per-item put and pull predicates the fixed group modes cannot express.
CanAcceptItem and CanReleaseItem work everywhere. They are wired to the SortableJS group functions on WebAssembly, so the drag is refused as the pointer moves, and they are enforced again in .NET when the drop is applied - which is what makes them hold on Blazor Server, and for every item of a MultiDrag selection rather than only the one under the pointer, since SortableJS asks its group functions about that one alone.
MoveDecision is WebAssembly only: it steers where an item lands while the pointer is still moving, which nothing can do after the fact. Setting it under Blazor Server throws PlatformNotSupportedException rather than silently never taking effect.
| Axis | SortableJS 1.15.7 | This package |
|---|---|---|
| Options | 47 | 47 |
| Events | 15 | 15 |
The counts come from the actual vendored 1.15.7 source: 33 core options, 6 AutoScroll options, 2 OnSpill options, 2 Swap options, and 4 MultiDrag options. The event count is the 12 core callbacks plus MultiDrag select/deselect and OnSpill spill. Internal plugin hooks are excluded. Function-valued JavaScript options are represented by typed Blazor-friendly forms: local-storage SortableStoreOptions, SetDataText/SetDataTextSelector, SortableDirection, CSS filter and scroll-container selectors, and ShouldContinueNativeScrolling.
- In-place same-list, cross-list, and multi-item moves with reference identity preserved
- Automatic depth-independent registration for recursive lists
- Pull/put group policies, clone mode, and cross-type conversion that can decline an item
- Synchronous move, put and pull decisions on WebAssembly - veto a drop or override its position
- Accept-only drop zones, and per-item draggability
- MultiDrag, Swap, AutoScroll, RevertOnSpill, and RemoveOnSpill
- Stable keyed rendering, and defaults through DI or a static
- DOM rollback before Blazor mutation, full event coverage, and deterministic disposal
net6.0throughnet10.0