BlazorDualListbox 1.0.1

BlazorDualListbox

A generic, accessible dual-listbox (pick-list) component for Blazor. Two side-by-side list boxes with controls to move items between them — via buttons, double-click, or the keyboard.

• Render-mode agnostic — works in Blazor Server, WebAssembly, and .NET 8+ unified hosting.
• Multi-targets net6.0, net8.0, and net10.0.
• No CSS framework dependency — clean default styling via CSS isolation, themeable with CSS custom properties. Bring Bootstrap/Tailwind/your own classes if you want them.
• Accessible — role="listbox"/role="option", aria-multiselectable, aria-selected, managed focus, and full keyboard operability.
• Two-way bindable — the parent stays the source of truth; the component only mutates the bound collections on an actual move.

Installation

dotnet add package BlazorDualListbox

Add the namespace to _Imports.razor (or the individual page):

@using BlazorDualListbox

Quick start

@using BlazorDualListbox

<DualListbox TItem="Person"
             @bind-Source="available"
             @bind-Selected="chosen"
             TextSelector="p => p.Name"
             ValueSelector="p => p.Id"
             Filterable="true"
             SourceHeader="Available"
             SelectedHeader="Selected"
             OnMoved="HandleMoved" />

@code {
    private IEnumerable<Person> available = new List<Person>
    {
        new(1, "Alice"), new(2, "Bob"), new(3, "Carol"),
    };
    private IEnumerable<Person> chosen = new List<Person>();

    private void HandleMoved(DualListboxMoveEventArgs<Person> e)
        => Console.WriteLine($"{e.Items.Count} item(s) moved {e.Direction}");

    public record Person(int Id, string Name);
}

Source and Selected are both @bind-able. Because the component raises the change callbacks on every move, your bound fields always reflect the current state.

Moving items

Selection: click to select, Ctrl/Cmd+click to toggle, Shift+click to select a range, Ctrl/Cmd+A to select all visible.

Keyboard: focus a list, then ↑/↓/Home/End to navigate, Space to toggle selection, Enter to move highlighted items.

Parameters

Data

Presentation

Button styling

Classes compose as dl-btn + ButtonClass + the per-button class — the built-in dl-btn is always kept, so you're adding to the default styling rather than replacing it.

<DualListbox TItem="Person"
             @bind-Source="available"
             @bind-Selected="chosen"
             ButtonClass="btn"
             AddSingleButtonClass="btn-primary"
             RemoveSingleButtonClass="btn-danger" />

The › button above renders as class="dl-btn btn btn-primary".

Behaviour

Any unmatched attributes (e.g. class, id, data-*) are splatted onto the root element.

Events

Theming

The component ships with CSS isolation and exposes CSS custom properties. Override them from your own stylesheet on .dl-root (or any ancestor):

.dl-root {
    --dl-gap: 0.5rem;
    --dl-border-color: #ccc;
    --dl-radius: 6px;
    --dl-bg: #fff;
    --dl-fg: #1a1a1a;
    --dl-muted-fg: #666;
    --dl-hover-bg: rgba(0, 0, 0, 0.05);
    --dl-highlight-bg: #2563eb;
    --dl-highlight-fg: #fff;
    --dl-accent: #2563eb;
    --dl-list-height: 16rem;
    --dl-min-width: 12rem;
}

For button styling specifically, prefer the *ButtonClass parameters described above.

Accessibility

Each list is a role="listbox" with aria-multiselectable="true"; items are role="option" with aria-selected. Focus is tracked with aria-activedescendant, and the component is fully operable by keyboard. This is a deliberate differentiator versus many existing components.

Requirements

• .NET 6, .NET 8, or .NET 10 (the package multi-targets net6.0;net8.0;net10.0).
• Works with any Blazor render mode (Server, WebAssembly, or .NET 8+ Auto/unified hosting).

Contributing

Issues and pull requests are welcome. The repository contains the component (RCL), a demo app, and a bUnit test suite:

git clone <repository-url>
cd blazor-dual-listbox/src
dotnet build
dotnet test

Run the demo app to explore the component interactively:

dotnet run --project DemoApp/DemoApp.csproj

Then browse to /dual-listbox.

License

MIT