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.
```html
AppleOrangeBananaLimeBlueberryPlum
```
## Installation
You can import through CDN:
```html
```
Or, you may install through [NPM](https://www.npmjs.com/package/@auroratide/reorder-list) and include it as part of your build process:
```
$ npm i @auroratide/reorder-list
```
```javascript
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:
```html
[Drag]Apple[Drag]Orange[Drag]Banana[Drag]Lime[Drag]Blueberry[Drag]Plum
```
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.
```html
AppleOrangeBananaKiwi
```
**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.
```html
Drag: Drag: Drag: Drag:
```
## 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.
```css
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.
```js
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.
```html
FruitAppleOrangeBananaKiwiVegetableTomatoCarrotSquashLettuceGrainWheatBarleyRyeRice
```
## 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.
```html
[Drag]Apple[Drag]Orange[Drag]Banana
```
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.
---
_Source: https://npm.io/package/@auroratide/reorder-list · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._