BlazorSortable 8.0.0

BlazorSortable

A Blazor component that wraps SortableJS, a library for drag-and-drop sorting.

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 and the base stylesheet automatically when the first Sortable component is initialized.

SortableOptions

AddSortable accepts an optional configuration delegate:

You can also pass a preconfigured SortableOptions instance:

builder.Services.AddSortable(new SortableOptions
{
    AutoLoadSortableJs = false,
    AutoLoadStylesheet = false,
    Defaults =
    {
        ForceFallback = false,
        FallbackOnBody = 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.

Bundled Styles

The bundled stylesheet contains only the default helper styles used by BlazorSortable:

.sortable-ghost {
    visibility: hidden;
}

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

.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 it 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.

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.

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.

• 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.