Skip to content
Razor catalogue

On this page

@addTagHelper *, Webority.Ui.Razor

Basic

Hold the order in state and write each drop back, with an id for each item and a label that names it.

Release steps
Design review
Build the feature
Test on staging
Ship to production
Show code
<app-sortable-list aria-label="Release steps" name="order">
    <app-sortable-item id="design" label="Design review"></app-sortable-item>
    <app-sortable-item id="build" label="Build the feature"></app-sortable-item>
    <app-sortable-item id="test" label="Test on staging"></app-sortable-item>
    <app-sortable-item id="ship" label="Ship to production"></app-sortable-item>
</app-sortable-list>

Handle only

Use a handle when the item body must stay selectable, or the page scrolls by touch.

Drag from the handle
Priya Sharma
Design lead
Arjun Mehta
Engineer
Neha Kapoor
Product manager
Show code
<app-sortable-list aria-label="Team" handle="true">
    <app-sortable-item id="a" label="Priya Sharma">...</app-sortable-item>
    <app-sortable-item id="b" label="Arjun Mehta">...</app-sortable-item>
    <app-sortable-item id="c" label="Neha Kapoor">...</app-sortable-item>
</app-sortable-list>

Disabled items

Mark a pinned first or last entry as disabled, so it cannot be picked up while the others move past it.

A pinned first item
Introduction (pinned)
Pricing
FAQ
Contact
Show code
<app-sortable-list aria-label="Sections">
    <app-sortable-item id="intro" label="Introduction (pinned)" disabled="true"></app-sortable-item>
    <app-sortable-item id="pricing" label="Pricing"></app-sortable-item>
    <app-sortable-item id="faq" label="FAQ"></app-sortable-item>
    <app-sortable-item id="contact" label="Contact"></app-sortable-item>
</app-sortable-list>

Handle on hover

Show each handle only when someone points at its item, so the list reads cleanly until it is needed.

Priorities
Alpha
Beta
Gamma
Show code
<app-sortable-list aria-label="Priorities" handle-display="Hover">
    <app-sortable-item id="a" label="Alpha"></app-sortable-item>
    <app-sortable-item id="b" label="Beta"></app-sortable-item>
    <app-sortable-item id="c" label="Gamma"></app-sortable-item>
</app-sortable-list>

Borderless

Remove the border and fill from each item for a list that sits inside a panel with its own frame.

Priorities, unframed
Alpha
Beta
Gamma
Show code
<app-sortable-list aria-label="Priorities" bordered="false">
    <app-sortable-item id="a" label="Alpha"></app-sortable-item>
    <app-sortable-item id="b" label="Beta"></app-sortable-item>
    <app-sortable-item id="c" label="Gamma"></app-sortable-item>
</app-sortable-list>

Wrapping row

Use a horizontal list for a row of tags that wraps onto more lines, ordered by pointer position.

Tags
Alpha
Beta
Gamma
Delta
Epsilon
Show code
<app-sortable-list aria-label="Tags" orientation="Orientation.Horizontal">
    <app-sortable-item id="alpha" label="Alpha"></app-sortable-item>
    <app-sortable-item id="beta" label="Beta"></app-sortable-item>
    <app-sortable-item id="gamma" label="Gamma"></app-sortable-item>
    <app-sortable-item id="delta" label="Delta"></app-sortable-item>
    <app-sortable-item id="epsilon" label="Epsilon"></app-sortable-item>
</app-sortable-list>

Between lists

Give lists the same group so items move between them, and let each list report its own new order.

A two-column board

To do

Write the brief
Draft the layout
Review copy

Done

Publish the page
Show code
<app-sortable-list aria-label="To do" group="steps" name="todo">...</app-sortable-list>
<app-sortable-list aria-label="Done" group="steps" name="done">...</app-sortable-list>

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 label
Design review
Build the feature
Test on staging
Ship to production
items[].disabled: a pinned item cannot be picked up, the others move past it
Introduction (pinned)
Pricing
FAQ
Contact
items[].content: rich content replaces the label text
Priya Sharma
Design lead
Arjun Mehta
Engineer
Neha Kapoor
Product manager

reorderLabel

reorder-label="Reorder {name}" (default): names each handle for assistive tech, no visible effect
Alpha
Beta
Gamma
reorder-label="Move {name}": names each handle for assistive tech, no visible effect
Alpha
Beta
Gamma

onReorder

wui-sortable:change event: raised after each drop with the new order, no visible effect (React: onReorder)
Alpha
Beta
Gamma

ariaLabel

aria-label="Priorities": names the list for assistive tech, no visible effect
Alpha
Beta
Gamma

handle

handle="false" (default)
Alpha
Beta
Gamma
handle="true": drags only from the handle
Alpha
Beta
Gamma

group

group="steps": lists with the same group accept each other's items

To do

Write the brief
Draft the layout
Review copy

Done

Publish the page

name

name="order": posts the order as one hidden input per item, no visible effect
Alpha
Beta
Gamma

disabled

disabled="false" (default)
Alpha
Beta
Gamma
disabled="true": no item can be picked up
Alpha
Beta
Gamma

orientation

orientation="vertical" (default)
Alpha
Beta
Gamma
orientation="horizontal": orders by pointer position along a row
Alpha
Beta
Gamma
Delta
Epsilon

handleDisplay

handle-display="always" (default)
Alpha
Beta
Gamma
handle-display="hover": shows each handle on hover, focus or lift
Alpha
Beta
Gamma

bordered

bordered="true" (default)
Alpha
Beta
Gamma
bordered="false": no border, fill or padding around each item
Alpha
Beta
Gamma

className

class="wui-sortable": extra classes on the list element, no visible effect
Alpha
Beta
Gamma

Guidance

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.

vertical horizontal
always hover
true false
Four tasks Five tags One pinned item Empty list
Design review
Build the feature
Test on staging
Ship to production
React, generated from the controls
<AppSortableList items={[{ id: "design", label: "Design review" }, { id: "build", label: "Build the feature" }, { id: "test", label: "Test on staging" }, { id: "ship", label: "Ship to production" }]} onReorder={setIds} ariaLabel="Playground list" />
Razor, the same props
<app-sortable-list aria-label="Playground list">
    <app-sortable-item id="design" label="Design review" />
    <app-sortable-item id="build" label="Build the feature" />
    <app-sortable-item id="test" label="Test on staging" />
    <app-sortable-item id="ship" label="Ship to production" />
</app-sortable-list>

13 props. The 4 most used come first.

Used on most screens 4 props

PropTypeDefaultDescription
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

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