Skip to content

Keyboard and screen readers

Tab into a list, move between its items with the arrow keys, press Space to pick one up, the arrow keys to move it - → carries it over to the Sprint (where the columns stack, ↓ from the end of the Backlog) - Space to drop it and Escape to put it back. Every step is announced to screen readers. The buttons on each item move it without dragging at all (MoveAsync, MoveToAsync), as WCAG 2.5.7 asks.

Announcements in
Backlog
Sign-up page
Password reset
Audit log
Dark mode
Sprint
Search
Export to CSV

Backlog: Sign-up page, Password reset, Audit log, Dark mode

Sprint: Search, Export to CSV

What a screen reader hears

Nothing announced yet…

Moves (OnEnd, with its Input)

No moves yet…

Try it

  • Click English and press Tab twice: the focus lands on a Backlog item - the items of a list are a single tab stop, at the one focused last. ↓ moves the focus, Space picks the item up, ↓ moves it, Space drops it. Each step shows up under What a screen reader hears.
  • Pick an item up, press → to carry it into the Sprint, then Escape: it goes back to the Backlog.
  • Press the ↑ ↓ → buttons on an item: it moves without any drag, and the move is announced when it lands.
  • Switch the announcements to Deutsch and do it all again: the same steps, in another language.
  • Drag an item with the mouse: a pointer drag is announced when it starts and when it ends, and the move log says mouse instead of keyboard or api.

The keys

KeyNot draggingDragging
TabEnters the list at its last focused item; the list is a single tab stop.Drops the item where it is, and moves on.
Arrow keysMove the focus to the item in that direction.Move the item to the next place in that direction; past the end of its list, into the nearest list of the group that way.
Home / EndFocus the first / last item.Move the item to the start / end of its list.
Space / EnterPick the focused item up.Drop it.
Shift+SpaceIn a multi-drag list, select or deselect the focused item.-
Escape-Put it back where it was.
  • The arrows follow the layout - up and down a vertical list, along a row, right to left in an RTL one, row to row in a grid, from column to column of a board, into a nested list - because the browser looks for the next item, or list, in the direction of the key.
  • A keyboard drag moves the item itself, into another list too, and the focus follows it. Every rule applies as for a pointer: a refused position, a full list, a list of another group are announced as refused, and ConfirmDrop is asked on the drop. In swap mode the arrows move the highlight.
  • Keys pressed inside an item - on these buttons, in an input - are left alone: only an item itself, or its drag handle, answers them. Keyboard="false" turns it all off, and a Disabled list is not focusable.

What is announced, in your words

A list is a list of listitems, each described as a "sortable item" with the keyboard instructions, and named by AriaLabel. Each step of a drag is announced through a live region with the item's name (ItemLabel, or its ToString()), its position and the list it is in. The texts are a BortableMessages: pass your own through Messages - one list at a time, or every list of the app through the app-wide defaults.

public static readonly BortableMessages German = new()
{
    Instructions = "Leertaste oder Eingabetaste nimmt das Element auf. ...",
    RoleDescription = "sortierbares Element",
    PickedUp = a => $"{a.Item} aufgenommen. Position {a.Position} von {a.Count} in {a.List}.",
    Moved = a => $"{a.Item} auf Position {a.Position} von {a.Count} in {a.List} verschoben.",
    // Dropped, Canceled, Refused, Locked, SwapTarget, Selected, Deselected ...
};
MessageWhen
InstructionsRead with every item (aria-describedby).
RoleDescriptionWhat an item is called in place of "list item" (aria-roledescription).
PickedUpA drag starts.
MovedA keyboard drag, or a move made by code, moves the item.
SwapTargetIn swap mode, the item the dragged one will trade places with changes.
DroppedThe drag ends with a drop.
CanceledThe drag is cancelled, or its drop refused: by ConfirmDrop, or, for a multi-drag's gathering, by CanDrop.
RefusedA position the keyboard asked for is refused.
LockedA locked (Filter) item is asked to be picked up.
SelectionInstructionsAdded to Instructions in a MultiDrag list.
Selected / DeselectedShift+Space selects or deselects an item of a MultiDrag list.

Each message takes a BortableAnnouncement: Item, Position and Count (from 1), List, OldPosition, FromList, Returned (back where it was picked up), in swap mode Target, and for a selection Selected, the number of items selected. A drag is announced in the messages of the list it started in.

Dragging is never the only way

A keyboard drag covers keyboard and switch users. MoveAsync(item, newIndex) and MoveToAsync(item, listId, newIndex) give an app the buttons and menus that WCAG 2.5.7 (dragging movements) asks for, and that some screen readers in browse mode need. They move an item exactly as a drag would: the same rules decide, ConfirmDrop is asked, the items slide, the events follow with Input set to Api, and the move is announced. Both return true when the item moved, and refuse while a drag is in progress.

<Bortable @ref="_list" @bind-Items="_items" TItem="string">
    <ItemTemplate Context="item">
        @item
        <button @onclick="() => _list.MoveAsync(item, Math.Max(0, _items.IndexOf(item) - 1))">↑</button>
    </ItemTemplate>
</Bortable>

The focus outline of an item, and the dashed one of an item picked up, are drawn by the stylesheet - in forced colours (Windows high contrast) too - and the slides are skipped when the system asks for reduced motion.

An unhandled error has occurred. Reload 🗙