Svelte Sortable List

A package to create accessible sortable lists in Svelte.

Live demos:

• Netlify
• Vercel

Table of contents

• Features
• Get started
  • Install it
  • Import it
  • Use it
• Accessibility
  • Keyboard navigation
  • Screen reader announcements customization
• Components
  • <SortableList.Root> props
  • <SortableList.Root> events
  • <SortableList.Item> props
• Utilities
• Transitions
• Types
• Styles
  • Selectors
  • Custom properties
• Motivation

Features

• Mouse, keyboard and touch support.
• Screen reader support (customizable).
• Vertical and horizontal directions.
• Varying heights.
• Drag handle.
• Wrapping.
• Auto scrolling.
• Customizable transitions.
• Lockable axis.
• Remove on drop outside.
• Nested interactive elements support.
• <dialog> support.
• RTL support.
• Un-opinionated styling.
• Custom classes support.
• Typescript definitions.
• No dependencies.

Get started

Install it

pnpm install @rodrigodagostino/svelte-sortable-list

npm install @rodrigodagostino/svelte-sortable-list

yarn add @rodrigodagostino/svelte-sortable-list

Import it

<script lang="ts">
    import { SortableList } from '@rodrigodagostino/svelte-sortable-list';
</script>

Use it

<script lang="ts">
    import { SortableList, sortItems } from '@rodrigodagostino/svelte-sortable-list';

    let items: SortableList.ItemData[] = [
        {
            id: 'list-item-1',
            text: 'List item 1',
        },
        {
            id: 'list-item-2',
            text: 'List item 2',
        },
        {
            id: 'list-item-3',
            text: 'List item 3',
        },
        {
            id: 'list-item-4',
            text: 'List item 4',
        },
        {
            id: 'list-item-5',
            text: 'List item 5',
        },
    ];

    function handleDragEnd(event: SortableList.RootEvents['dragend']) {
        const { draggedItemIndex, targetItemIndex, isCanceled } = event.detail;
        if (!isCanceled && typeof targetItemIndex === 'number' && draggedItemIndex !== targetItemIndex)
            items = sortItems(items, draggedItemIndex, targetItemIndex);
    }
</script>

<SortableList.Root on:dragend={handleDragEnd}>
    {#each items as item, index (item.id)}
        <SortableList.Item {...item} {index}>
            <div class="ssl-item-content">
                <span class="ssl-item-content__text">{item.text}</span>
            </div>
        </SortableList.Item>
    {/each}
</SortableList.Root>

Accessibility

The following is a list of the accessibility features provided by the package:

Keyboard navigation

These are the steps to navigate and operate the list:

1. Press Tab to focus the list.
2. Press Arrow Up, Arrow Left, Arrow Down, Arrow Right, Home or End to focus the first item in the list.
3. Press Arrow Up or Arrow Left to move the focus to the previous item.
4. Press Arrow Down or Arrow Right to move the focus to the next item.
5. Press Home to move the focus to the first item.
6. Press End to move the focus to the last item.
7. Press Space to start dragging an item. When dragging, press Space again to drop the dragged item.
8. Press Arrow Up or Arrow Left to move the dragged item to the previous position.
9. Press Arrow Down or Arrow Right to move the dragged item to the next position.
10. Press Home to move the dragged item to the first position.
11. Press End to move the dragged item to the last position.
12. Press Escape to cancel the drag and return the item to its initial position.

Screen reader announcements customization

There are two main things that need to be considered to customize the screen reader announcements:

• The aria-description attribute: the keyboard navigation instructions (default: Press the arrow keys to move through the list items. Press Space to start dragging an item. When dragging, use the arrow keys to move the item around. Press Space again to drop the item, or Escape to cancel.).
• The announcements prop: the announcements to be read out by the screen reader during drag and drop operations.

In addition to those, you can also use the following too (accepted by both the <SortableList.Root> and <SortableList.Item> components):

• The aria-label attribute: the name of the list.
• The aria-labelledby attribute: the ID of the element that provides the name of the list.

The following example contains most of the code that you can find in the “With custom announcements” demo page, and it shows how we could translate the announcements to Spanish:

<script lang="ts">
    ...

    const announcements: SortableList.RootProps['announcements'] = {
        lifted: (_, draggedItemIndex) => {
            return `Ha levantado un item en la posición ${draggedItemIndex + 1}.`;
        },
        dragged: (_, draggedItemIndex, __, targetItemIndex) => {
            const startPosition = draggedItemIndex + 1;
            const endPosition = targetItemIndex + 1;
            const result =
                startPosition !== endPosition
                    ? `desde la posición ${startPosition} a la posición ${endPosition}`
                    : `de vuelta a su posición inicial de ${startPosition}`;
            return `Ha movido el item ${result}.`;
        },
        dropped: (_, draggedItemIndex, __, targetItemIndex) => {
            const startPosition = draggedItemIndex + 1;
            const endPosition = typeof targetItemIndex === 'number' ? targetItemIndex + 1 : null;
            const result =
                endPosition === null
                    ? `Se ha mantenido en su posición inicial de ${startPosition}`
                    : startPosition !== endPosition
                        ? `Se ha movido desde la posición ${startPosition} a la posición ${endPosition}`
                        : `Ha vuelto a su posición inicial de ${startPosition}`;
            return `Ha soltado el item. ${result}.`;
        },
        canceled: (_, draggedItemIndex) => {
            return `Ha cancelado el arrastre. El item ha vuelto a su posición inicial de ${draggedItemIndex + 1}.`;
        },
    };
</script>

<SortableList.Root
    ...
    aria-description="Presione las flechas para desplazarte por los elementos de la lista. Presione Espacio para empezar a arrastrar un elemento. Al arrastrar, use las flechas para moverlo. Presione Espacio de nuevo para soltar el elemento o Escape para cancelar."
    {announcements}
>
    ...
</SortableList.Root>

Components

The following is a list of the available components inside the package:

[!WARNING] It is possible to avoid the <SortableList.ItemRemove> component and just go with a <button> element to trigger the removal of an item, but keep in mind that this component doesn’t just fire a click event, it will also focus the next item in the list if the user is using the keyboard to press the remove button. Otherwise, after the focused element is removed, the focus will fall back to the <body>.

<SortableList.Root> props

[!WARNING] For the time being, the support for wrapping is limited to lists that are horizontal and have items with the exact same width and height. Any other variation might not produce the expected results.

<SortableList.Root> events

[!NOTE] Events are fired in the order they are displayed below.

event: {
  detail: null
}

event: {
  detail: {
    deviceType: 'pointer' | 'keyboard',
    draggedItem: HTMLLIElement,
    draggedItemId: string,
    draggedItemIndex: number,
    isBetweenBounds: boolean,
    canRemoveOnDropOut: boolean
  }
}

event: {
  detail: {
    deviceType: 'pointer' | 'keyboard',
    draggedItem: HTMLLIElement,
    draggedItemId: string,
    draggedItemIndex: number,
    targetItem: HTMLLIElement | null,
    targetItemId: string | null,
    targetItemIndex: number | null,
    isBetweenBounds: boolean,
    canRemoveOnDropOut: boolean
  }
}

event: {
  detail: {
    deviceType: 'pointer' | 'keyboard',
    draggedItem: HTMLLIElement,
    draggedItemId: string,
    draggedItemIndex: number,
    targetItem: HTMLLIElement | null,
    targetItemId: string | null,
    targetItemIndex: number | null,
    isBetweenBounds: boolean,
    canRemoveOnDropOut: boolean
  }
}

event: {
  detail: {
    deviceType: 'pointer' | 'keyboard',
    draggedItem: HTMLLIElement,
    draggedItemId: string,
    draggedItemIndex: number,
    targetItem: HTMLLIElement | null,
    targetItemId: string | null,
    targetItemIndex: number | null,
    isBetweenBounds: boolean,
    canRemoveOnDropOut: boolean,
    isCanceled: boolean
  }
}

event: {
  detail: null
}

<SortableList.Item> props

Utilities

Example:

<script lang="ts">
    import { ... removeItem, sortItems } from '@rodrigodagostino/svelte-sortable-list';
    ...

    function handleDragEnd(event: SortableList.RootEvents['dragend']) {
        const { draggedItemIndex, targetItemIndex, isCanceled } = event.detail;
        if (!isCanceled && typeof targetItemIndex === 'number' && draggedItemIndex !== targetItemIndex)
            items = sortItems(items, draggedItemIndex, targetItemIndex);
    }

    function handleRemoveClick(event: MouseEvent) {
        const target = event.target as HTMLElement;
        const item = target.closest<HTMLLIElement>('.ssl-item');
        const itemIndex = Number(item?.dataset.itemIndex);
        if (!item || itemIndex < 0) return;
        items = removeItem(items, itemIndex);
    }
</script>

<SortableList.Root on:dragend={handleDragEnd}>...</SortableList.Root>

Transitions

{
  delay: number
  duration: number
  easing: function
  x: number
  y: number
  opacity: number
}

Example:

<script lang="ts">
    import { ... scaleFly } from '@rodrigodagostino/svelte-sortable-list';
    ...
</script>

<SortableList.Root>
    {#each items as item, index (item.id)}
        <SortableList.Item
            {...item}
            {index}
            transitionIn={(node) => scaleFly(node, { duration: 320, x: -200 })}
            transitionOut={(node) => scaleFly(node, { duration: 320, x: 200 })}
        >
            ...
        </SortableList.Item>
    {/each}
</SortableList.Root>

Types

Example:

<script lang="ts">
    import type { SortableList } from '@rodrigodagostino/svelte-sortable-list';
    ...

    function handleDrop(event: SortableList.RootEvents['drop']) {
        const { draggedItemIndex, isBetweenBounds, canRemoveOnDropOut } = event.detail;
        if (!isBetweenBounds && canRemoveOnDropOut) items = removeItem(items, draggedItemIndex);
    }

    function handleDragEnd(event: SortableList.RootEvents['dragend']) {
        const { draggedItemIndex, targetItemIndex, isCanceled } = event.detail;
        if (!isCanceled && typeof targetItemIndex === 'number' && draggedItemIndex !== targetItemIndex)
            items = sortItems(items, draggedItemIndex, targetItemIndex);
    }
</script>

Styles

If you want to make use of the styles present in the demo pages, import them in your project like so:

<script>
    import 'svelte-sortable-list/styles.css';
</script>

Selectors

[!IMPORTANT] To customize the appearance of the list items and ghost element (and not cause any conflicts or interferences with the core styles and transitions), the .ssl-item and .ssl-ghost selectors can be used as long as no transitions are applied directly to them. Another option is to create a wrapping element for the item’s content (like the element with the .ssl-item-content class included in one of the examples), which should be the direct child of the element with the .ssl-item class (the ghost element will simply mirror the list item’s content and appearance).

This is a list of the selectors you can use to style this library’s components to your heart’s desire:

[!TIP] Combining the available selectors appropriately should be enough to style the list and the list items to your heart’s content. For example, the following would target an element with a custom selector inside of the <SortableListGhost> component when canRemoveOnDropOut is enabled and is being dragged outside of the list limits:

.ssl-ghost[data-can-remove-on-drop-out='true']
    .ssl-item[data-is-between-bounds='false']
    .ssl-item-content {
    background-color: var(--ssl-rose-300);
    border-color: var(--ssl-rose-400);
}

If you find that your particular case is not covered, please, feel free to submit a request :)

Custom properties

Motivation

While working on a SvelteKit project, I ran into the need of adding drag-and-drop capabilities to a couple of items lists, for which I decided to make use of SortableJS, which is certainly a popular option. I implemented it through a Svelte Action and it provided just what I needed, or so it seemed. After a while I realized I was not only missing touch screen support (since it was built with the HTML Drag and Drop API), but also accessibility was nowhere to be seen, and seems there are no plans to work on it.

I was not able to find any other suitable option, so this problem felt like a good opportunity to build my own package. And so while doing some research to try and understand the implications of such feature, I ran into a very interesting article and a very interesting talk by Vojtech Miksu which really guided me through the different paths available, their advantages, pain points and limitations to create a drag-and-drop system, putting particular focus on accessibility and touch screen support.

Even though React Movable was built for React, it served as my main inspiration when building this package. So thank you again, Vojtech :)