On this page
@addTagHelper *, Webority.Ui.RazorBasic
Hold the order in state and write each drop back, with an id for each item and a label that names it.
Handle only
Use a handle when the item body must stay selectable, or the page scrolls by touch.
Disabled items
Mark a pinned first or last entry as disabled, so it cannot be picked up while the others move past it.
Handle on hover
Show each handle only when someone points at its item, so the list reads cleanly until it is needed.
Borderless
Remove the border and fill from each item for a list that sits inside a panel with its own frame.
Wrapping row
Use a horizontal list for a row of tags that wraps onto more lines, ordered by pointer position.
Between lists
Give lists the same group so items move between them, and let each list report its own new order.
To do
Done
Every option
Every value of every prop, one cell each.
items
items: no app-sortable-item children (default)items: four tasks, each with an id and a labelitems[].disabled: a pinned item cannot be picked up, the others move past ititems[].content: rich content replaces the label textreorderLabel
reorder-label="Reorder {name}" (default): names each handle for assistive tech, no visible effectreorder-label="Move {name}": names each handle for assistive tech, no visible effectonReorder
wui-sortable:change event: raised after each drop with the new order, no visible effect (React: onReorder)ariaLabel
aria-label="Priorities": names the list for assistive tech, no visible effecthandle
handle="false" (default)handle="true": drags only from the handlegroup
group="steps": lists with the same group accept each other's itemsTo do
Done
name
name="order": posts the order as one hidden input per item, no visible effectdisabled
disabled="false" (default)disabled="true": no item can be picked uporientation
orientation="vertical" (default)orientation="horizontal": orders by pointer position along a rowhandleDisplay
handle-display="always" (default)handle-display="hover": shows each handle on hover, focus or liftbordered
bordered="true" (default)bordered="false": no border, fill or padding around each itemclassName
class="wui-sortable": extra classes on the list element, no visible effectGuidance
What to do, and what to avoid.
Use it when
- The person decides the order: priorities, steps, sections, the columns of a report.
- A short list where seeing every item at once is the point.
Reach for something else when
- Rows the person adds and removes, not just orders. → AppRepeater
- Sorting a table by a column. → AppDataTable
- Choosing from options, not ordering them. → AppSelect mode="multiple"
Reference
Try every prop, read the full list, and check keyboard and screen reader behaviour.
13 props. The 4 most used come first.
Used on most screens 4 props
| Prop | Type | Default | Description |
|---|---|---|---|
| aria-labeldefault - | string | - | Names the list for assistive tech; also used in announcements when an item moves between lists. |
| namedefault - | string | - | Form field name; posts the order as one hidden input per item. |
| groupdefault - | string | - | Name shared by lists that accept each other's items. |
| handledefault false | bool | false | Drag only from the handle. Without it an item can also be dragged from its body (links, buttons and inputs inside it keep working). |
Less common 9 props
| Prop | Type | Default | Description |
|---|---|---|---|
| handle-displaydefault always | always | hover | always | always shows every handle; hover shows it on item hover, handle focus, while lifted, and always on touch screens. Hover also turns the handle on. |
| bordereddefault true | bool | true | False draws no border, fill or padding around each item. |
| disableddefault false | bool | false | No item can be picked up. |
| orientationdefault vertical | vertical | horizontal | vertical | Direction the items run; horizontal also covers a wrapping row. |
| reorder-labeldefault Reorder {name} | string | Reorder {name} | Replaces the built-in English text, for other languages. {name} is the item's label. |
| app-sortable-item iddefault - | string | - | What the order reports for this item; unique in the list. |
| app-sortable-item labeldefault id | string | id | Names the item to assistive tech, and is shown when the item has no content. |
| app-sortable-item disableddefault false | bool | false | This item cannot be picked up; the others can still move past it. |
| wui-sortable:changedefault - | event | - | Raised on each list that a drop changes; its detail.ids is that list's new order. |
Screen reader
3 notes- Focus an item's handle, press Space to lift it, the arrow keys to move it, Space to drop it and Escape to cancel.
- Every move is announced to screen readers, including a move between lists.
- The list has role list and each item role listitem; each handle is a button named Reorder followed by the item label.