BlazorSortable 8.1.0

BlazorSortable

A Blazor component that wraps SortableJS, a JavaScript library for reorderable drag-and-drop lists.

Inspired by BlazorSortable and represents an improved and extended implementation.

Installation

Via NuGet Package Manager

Search for BlazorSortable in NuGet Package Manager.

Via .NET CLI

dotnet add package BlazorSortable

Via PackageReference

Add to your .csproj file:

<ItemGroup>
  <PackageReference Include="BlazorSortable" Version="8.*" />
</ItemGroup>

Setup

1. Add BlazorSortable services in the Program.cs file of the app where the component runs (InteractiveWebAssembly components require registration in the client app):

   using BlazorSortable;
   
   // ...
   
   builder.Services.AddSortable();
   

2. Add the using directive in _Imports.razor:

   @using BlazorSortable
   

By default, BlazorSortable loads the bundled SortableJS 1.15.7 script, the base stylesheet, and the highlight stylesheet automatically when the first Sortable component is initialized.

SortableOptions

AddSortable accepts an optional configuration delegate:

builder.Services.AddSortable(options =>
{
    options.AutoLoadStylesheet = false;
    options.Defaults.ForceFallback = false;
});

You can also pass a preconfigured SortableOptions instance:

builder.Services.AddSortable(new SortableOptions
{
    AutoLoadStylesheet = false,
    Defaults =
    {
        ForceFallback = false,
        RevertOnSpill = true
    }
});

SortableDefaults

Manual Asset Loading

If you want to manage these assets yourself, disable automatic loading:

builder.Services.AddSortable(options =>
{
    options.AutoLoadSortableJs = false;
    options.AutoLoadStylesheet = false;
});

When AutoLoadSortableJs is disabled, SortableJS must be available globally as Sortable before any Sortable component initializes.

If you want to keep the base helper styles but provide your own selected item and swap highlight styles, disable only the highlight stylesheet:

builder.Services.AddSortable(options =>
{
    options.AutoLoadHighlightStylesheet = false;
});

Bundled Styles

The bundled base stylesheet _content/BlazorSortable/blazor-sortable.css contains only the default helper styles used by BlazorSortable:

.sortable-ghost {
    visibility: hidden;
}

.sortable-fallback {
    opacity: 1 !important;
}

The bundled highlight stylesheet _content/BlazorSortable/blazor-sortable-highlights.css contains the default visual styles for multi-drag selection and swap highlighting:

.sortable-selected {
    outline: var(--blazor-sortable-selected-outline-width, 2px) solid var(--blazor-sortable-selected-outline-color, Highlight);
    outline-offset: calc(-1 * var(--blazor-sortable-selected-outline-width, 2px));
}

.sortable-swap-highlight {
    outline: var(--blazor-sortable-swap-highlight-outline-width, 2px) solid var(--blazor-sortable-swap-highlight-outline-color, Highlight);
    outline-offset: calc(-1 * var(--blazor-sortable-swap-highlight-outline-width, 2px));
}

You can disable all automatic stylesheet loading with AutoLoadStylesheet = false if you want to provide these styles yourself.

Usage Example

<div class="sortable-sample">
    <Sortable Items="todoItems"
              Group="tasks"
              Class="sortable-column">
        <div class="sortable-item">
            @context
        </div>
    </Sortable>

    <Sortable Items="doneItems"
              Group="tasks"
              Class="sortable-column">
        <div class="sortable-item">
            @context
        </div>
    </Sortable>

    <Sortable TItem="object"
              Group="delete"
              PutMode="SortablePutMode.Groups"
              PutGroups="@(["tasks"])"
              Class="sortable-delete" />
</div>

<style>
    .sortable-sample {
        display: flex;
        gap: 16px;
    }

    .sortable-column,
    .sortable-delete {
        width: 180px;
        min-height: 96px;
        padding: 12px;
        border: 2px dashed #d0d7de;
        border-radius: 6px;
    }

    .sortable-column {
        display: flex;
        flex-direction: column;
        gap: 8px;
    }

    .sortable-delete {
        border-color: #dc3545;
        overflow: hidden;
    }

    .sortable-item {
        padding: 10px 12px;
        border: 1px solid #d0d7de;
        border-radius: 6px;
        background: white;
        color: #24292f;
        cursor: grab;
        user-select: none;
    }
</style>

@code {
    private readonly IList<string> todoItems = ["Write docs", "Add tests", "Publish package"];
    private readonly IList<string> doneItems = ["Create project"];
}

API

Sortable

SortablePullMode

SortablePutMode

Events

OnUpdate, OnAdd, OnRemove, and OnChange receive a SortableEventArgs<TItem> parameter.

OnSelect and OnDeselect receive a SortableSelectionEventArgs<TItem> parameter.

OnSpill receives a SortableSpillEventArgs<TItem> parameter.

Functions like PullFunction, PutFunction, and ConvertFunction use a SortableTransferContext<T> parameter.

SortableEventArgs

The SortableEventArgs<TItem> class provides information about sorting operations.

SortableChangeOperation

The SortableChangeOperation enum defines the operation that changed a Sortable component's items.

SortableSelectionEventArgs

The SortableSelectionEventArgs<TItem> class provides information about multi-drag selection changes.

SortableSpillEventArgs

The SortableSpillEventArgs<TItem> class provides information about a spill operation.

SortableTransferContext

The SortableTransferContext<TItem> class represents the context of transferring an item between sortable components.

SortableInfo

The SortableInfo type provides sortable identity information.

SortableTryConvertFunc<TItem>

The SortableTryConvertFunc<TItem> delegate represents a method that attempts to convert an incoming item from a sortable transfer context to a strongly typed item.

This delegate is used by the ConvertFunction parameter when items are transferred between Sortable components with different item types.

public delegate bool SortableTryConvertFunc<TItem>(
    SortableTransferContext<object> context,
    out TItem item)
    where TItem : notnull;

The method should return true when conversion succeeds. If conversion is not possible, it should return false and set item to its default value.

Notes

• Order of events when moving items between components:

  For a non-clone move between components:

  1. OnAdd is triggered first - during this event, the item is still present in the source component.
  2. OnRemove is triggered after.

• Type mismatch / failed conversion:

  If the dragged item is assignable to the target item type, it is added as-is and ConvertFunction is not called.
  If the item is not assignable, ConvertFunction is used when provided.
  If no ConvertFunction is provided, or it returns false, the item is not accepted and remains in its original position. ConvertFunction receives a SortableTransferContext<object> because the source item type may be different from the target TItem.

• Moving items between lists with fallback mode:

  Components that exchange items should use the same effective ForceFallback value. Mixing fallback and native HTML5 drag behavior between source and target lists can produce inconsistent DOM and pointer behavior during cross-list moves.

• Do not create item lists inline in markup:

  Pass a stable list instance from @code. Avoid expressions that create a new list on every render, for example:

  <Sortable Items="@(["One", "Two", "Three"])">
      @context
  </Sortable>
  

  Use a field or property with a stable backing collection instead:

  <Sortable Items="items">
      @context
  </Sortable>
  
  @code {
      private readonly IList<string> items = ["One", "Two", "Three"];
  }
  

• Dragging issues on scrolled page:

  If the dragged element appears misaligned when the page is scrolled inside a custom scroll container, set

  ForceFallback="false"
  

  or

  FallbackOnBody="true"
  

• Server-side interactivity limitation:

  PullFunction and PutFunction require synchronous JS-to-.NET calls used by SortableJS, which are only available when the component runs on WebAssembly. These options are not supported with server-side interactivity and will throw a PlatformNotSupportedException.

  Note: Prerendering is supported, but these options require WebAssembly at runtime.