@auroratide/reorder-list

The reorder-list Elements

View this page with live demos!

The reorder-list and reorder-item elements represent an ordered list of items that can be reordered. They are built with accessibility in mind and implement the WAI-ARIA guidelines for rearrangable listboxes.

<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 and reorder-item 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.

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: #ddd;
    border-radius: 0.5em;
    width: min(400px, 100%);
    padding: 0.5em;
    display: flex;
    flex-direction: column;
    gap: 0.5em;
}

reorder-item {
    background: #fff;
    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: #2573C1;
}

Events

The reorder-list element dispatches the following events:

Name	When Triggered
reorder-list:change	Whenever an item in the list is reordered

The reorder-list:change event contains a reference to the item that was reordered, its previous position in the list, and its new position.

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

Accessibility

This custom element is build with accessibility in mind! It follows the WAI-ARIA guidelines for rearrangable listboxes (the listbox and option roles).

• When focus enters the list, focus goes to the currently active list item.
• 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.