The reorder-list Elements

The reorder-list, reorder-item, and reorder-handle elements represent an ordered list of items that can be reordered. They are built with accessibility in mind and implement list/listitem semantics with a button handle.

<reorder-list>
	<reorder-item>Apple</reorder-item>
	<reorder-item>Orange</reorder-item>
	<reorder-item>Banana</reorder-item>
	<reorder-item>Lime</reorder-item>
	<reorder-item>Blueberry</reorder-item>
	<reorder-item>Plum</reorder-item>
</reorder-list>

Installation

You can import through CDN:

<script type="module" src="https://unpkg.com/@auroratide/reorder-list/lib/define.js"></script>

Or, you may install through NPM and include it as part of your build process:

$ npm i @auroratide/reorder-list

import '@auroratide/reorder-list/lib/define.js'

Usage

reorder-list, reorder-item, and reorder-handle are markup elements that you can use in your HTML document. To use them together, it is best to follow these guidelines:

• reorder-item elements must be direct descendents of a reorder-list element. This is similar to how li must directly descend ol.
• reorder-handle elements are optional, but if included must be a descendent of a reorder-item element.

Reorder Handles

By default, when there is no explicit handle provided, the entire reorder item provides a default draggable handle that covers the item. If you only want a part of the item to be draggable, then you can use reorder-handle, like so:

<reorder-list>
	<reorder-item>
		<reorder-handle><span>[Drag]</span></reorder-handle>
		<span>Apple</span>
	</reorder-item>
	<reorder-item>
		<reorder-handle><span>[Drag]</span></reorder-handle>
		<span>Orange</span>
	</reorder-item>
	<reorder-item>
		<reorder-handle><span>[Drag]</span></reorder-handle>
		<span>Banana</span>
	</reorder-item>
	<reorder-item>
		<reorder-handle><span>[Drag]</span></reorder-handle>
		<span>Lime</span>
	</reorder-item>
	<reorder-item>
		<reorder-handle><span>[Drag]</span></reorder-handle>
		<span>Blueberry</span>
	</reorder-item>
	<reorder-item>
		<reorder-handle><span>[Drag]</span></reorder-handle>
		<span>Plum</span>
	</reorder-item>
</reorder-list>

Handles have the following accessibility affordances:

• Handles participate in the tab order of the document.
• Handles are labeled as "Reorder {item name}", to instruct screen readers what the handle is for.
• The default handle becomes visible on focus, indicating which item is focused.

Orientation

By default, orientation is "vertical", meaning you drag items up and down. Setting orientation to "horizontal" will allow you to reorder items left and right instead.

<reorder-list orientation="horizontal">
	<reorder-item>Apple</reorder-item>
	<reorder-item>Orange</reorder-item>
	<reorder-item>Banana</reorder-item>
	<reorder-item>Kiwi</reorder-item>
</reorder-list>

Note: Bidirectional reordering is not possible with this component. reorder-list is for lists, whereas bidirectional reordering would be for a grid of some kind; they are different semantics.

Ignoring Reorder Trigger

You may have an element within a reorder-item that you do not want triggering a reorder. For instance, an input element should not start dragging, and it should instead focus on the input.

Use the data-ignore-reorder attribute on any element within reorder-item in order to make that element not start dragging.

<reorder-list>
	<reorder-item>Drag: <input data-ignore-reorder type="text" value="Apple" /></reorder-item>
	<reorder-item>Drag: <input data-ignore-reorder type="text" value="Orange" /></reorder-item>
	<reorder-item>Drag: <input data-ignore-reorder type="text" value="Banana" /></reorder-item>
	<reorder-item>Drag: <input data-ignore-reorder type="text" value="Kiwi" /></reorder-item>
</reorder-list>

CSS Customization

Since these are native custom elements, they can be styled the same way as regular HTML elements.

Of note:

• reorder-item[data-dragging] will style the currently dragged item.

Here's an example of a customized list meant to look like reorderable cards.

reorder-list {
	list-style: none;
	background: oklch(22% 0.021 255);
	border-radius: 0.5em;
	width: min(400px, 100%);
	padding: 0.5em;
	display: flex;
	flex-direction: column;
	gap: 0.5em;
}

reorder-item {
	background: oklch(27% 0.02 255);
	border-radius: 0.25em;
	padding: 0.5em;
	box-shadow: 0 0.1em 0.15em #0002;
}

reorder-item ul {
	list-style: none;
	display: flex;
	flex-wrap: wrap;
	gap: 0.5em;
	padding: 0;
	margin: 0;
	font-size: 90%;
	color: oklch(64% 0.142 250);
}

Events

The reorder-list element dispatches the following events:

| Name | When Triggered | | ------------- | ------------- | | change | Whenever an item in the list is reordered | | commit | At the end of an item being dragged |

Both events contain a reference to the item that was reordered, its previous position in the list, and its new position.

list.addEventListener('change', e => {
	console.log(e.detail.item)
	console.log(e.detail.oldIndex)
	console.log(e.detail.newIndex)
})

The difference between change and commit is the change event happens any time an element changes order, including in the middle of a drag. The commit event only triggers at the end of a drag, so the old index in that event's details will represent the position of that item prior to the drag being started.

Nesting Lists

Nothing stops you from putting lists inside of lists.

<reorder-list orientation="horizontal">
	<reorder-item>
		<strong>Fruit</strong>
		<reorder-list>
			<reorder-item>Apple</reorder-item>
			<reorder-item>Orange</reorder-item>
			<reorder-item>Banana</reorder-item>
			<reorder-item>Kiwi</reorder-item>
		</reorder-list>
	</reorder-item>
	<reorder-item>
		<strong>Vegetable</strong>
		<reorder-list>
			<reorder-item>Tomato</reorder-item>
			<reorder-item>Carrot</reorder-item>
			<reorder-item>Squash</reorder-item>
			<reorder-item>Lettuce</reorder-item>
		</reorder-list>
	</reorder-item>
	<reorder-item>
		<strong>Grain</strong>
		<reorder-list>
			<reorder-item>Wheat</reorder-item>
			<reorder-item>Barley</reorder-item>
			<reorder-item>Rye</reorder-item>
			<reorder-item>Rice</reorder-item>
		</reorder-list>
	</reorder-item>
</reorder-list>

Filtering

You may have a list with some of the items hidden as a result of filtering. The reorder-list will still allow you to reorder the sublist!

Some important notes:

• The change and commit events continue to report the changes in the indexes of the overall list, not just the visible list.
• The end result of the reorder will be as if the invisible items were visible, for the sake of predictability.
• This works with arrow keys too for accessibility.

<reorder-list>
	<reorder-item>
		<reorder-handle><span>[Drag]</span></reorder-handle>
		<span>Apple</span>
	</reorder-item>
	<reorder-item hidden>
		<reorder-handle><span>[Drag]</span></reorder-handle>
		<span>Orange</span>
	</reorder-item>
	<reorder-item>
		<reorder-handle><span>[Drag]</span></reorder-handle>
		<span>Banana</span>
	</reorder-item>
</reorder-list>

If you need the distinction yourself, list.items() gives every item and list.visibleItems() only the ones on screen.

Accessibility

This custom element is build with accessibility in mind! It implements list/listitem semantics and uses handles to reorder the items.

• Each handle is a focusable item that participates in the tab order.
• Up and Down can be used to navigate the list, focusing on an element that will be reordered.
• Alt + Up/Down moves the currently selected list item up or down in the order.
• If orientation is horizontal, then Left and Right are used instead.
• A live region is used to announce the last change of order.

Reorder Announcer

List reordering is announced to assistive technology using a live region. This region is located at the end of the body document, with the data-reorder-list-announcer attribute. All reorder-list elements share the same announcement region.