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.
Backlog: Sign-up page, Password reset, Audit log, Dark mode
Sprint: Search, Export to CSV
What a screen reader hears
Moves (OnEnd, with its Input)
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
mouseinstead ofkeyboardorapi.
The keys
| Key | Not dragging | Dragging |
|---|---|---|
| Tab | Enters the list at its last focused item; the list is a single tab stop. | Drops the item where it is, and moves on. |
| Arrow keys | Move 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 / End | Focus the first / last item. | Move the item to the start / end of its list. |
| Space / Enter | Pick the focused item up. | Drop it. |
| Shift+Space | In 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
ConfirmDropis 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 aDisabledlist 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 ... };
| Message | When |
|---|---|
Instructions | Read with every item (aria-describedby). |
RoleDescription | What an item is called in place of "list item" (aria-roledescription). |
PickedUp | A drag starts. |
Moved | A keyboard drag, or a move made by code, moves the item. |
SwapTarget | In swap mode, the item the dragged one will trade places with changes. |
Dropped | The drag ends with a drop. |
Canceled | The drag is cancelled, or its drop refused: by ConfirmDrop, or, for a multi-drag's gathering, by CanDrop. |
Refused | A position the keyboard asked for is refused. |
Locked | A locked (Filter) item is asked to be picked up. |
SelectionInstructions | Added to Instructions in a MultiDrag list. |
Selected / Deselected | Shift+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.