Svelte Sortable List

A package to create accessible sortable lists in Svelte.

Live demo:

• Netlify
• Vercel

Table of contents

• Features
• Get started
  • Install it
  • Import it
  • Use it
• Keyboard navigation
• Components
  • <SortableList> props
  • <SortableList> events
  • <SortableItem> props
• Utilities
• Types
• Styles
  • Selectors
  • Custom properties
• Motivation

Features

• Accessibility focused (keyboard navigation and screen reader support).
• Drag and drop.
• Handle.
• Drop marker.
• Varying heights.
• Vertical and horizontal direction.
• Lockable axis.
• Remove on drop outside.
• Touch screen support.
• RTL support.
• Un-opinionated styling.
• 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, sortItems, type SortableListProps } from 'svelte-sortable-list';
</script>

Use it

<script lang="ts">
    import { SortableItem, SortableList, sortItems } from '$lib/index.js';
    import type { SortableItemData } from '$lib/types/index.js';
    import '$lib/styles.css';

    let items: SortableItemData[] = [
        {
            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 handleSort(event: CustomEvent<SortEventDetail>) {
        const { prevItemIndex, nextItemIndex } = event.detail;
        items = sortItems(items, prevItemIndex, nextItemIndex);
    }
</script>

<SortableList on:sort={handleSort}>
    {#each items as item, index (item.id)}
        <SortableItem id={item.id} {index}>
            <div class="ssl-item__content">
                {item.text}
            </div>
        </SortableItem>
    {/each}
</SortableList>

Keyboard navigation

The following is a list of steps to navigate and operate the Sortable List:

1. Press Tab to focus the list.
2. Press Arrow Up, Arrow Left, Arrow Down or Arrow Right 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 drag or drop an 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.

Components

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

You can create your own <Remove> component if you require it that way. Do so by importing the dispatch() function from this package (or create your own dispatcher), and make sure to use the event name and detail included in the example:

<script lang="ts">
    import { dispatch } from '@rodrigodagostino/svelte-sortable-list';
    import { Button } from '$lib/components';

    function handleRemove(event: MouseEvent) {
        const target = event.target as HTMLElement;
        if (target) dispatch(target, 'requestremove', { item: target.closest('.ssl-item') });
    };
</script>

<Button on:click={handleRemove}>Remove</Button>

<SortableList> props

<SortableList> events

event: {
  detail: {
    prevItemId: string,
    prevItemIndex: number,
    nextItemId: string,
    nextItemIndex: number
  }
}

event: {
  detail: {
    itemId: string,
    itemIndex: number
  }
}

<SortableItem> props

Utilities

Example:

<script lang="ts">
    import {
        SortableList,
        SortableItem,
        Remove,
        IconRemove,
        removeItem,
        sortItems,
    } from '$lib/index.js';
    import type { SortableItemData } from '$lib/types/index.js';

    let items: SortableItemData[] = [
        {
            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 handleSort(event: CustomEvent<SortEventDetail>) {
        const { prevItemIndex, nextItemIndex } = event.detail;
        items = sortItems(items, prevItemIndex, nextItemIndex);
    }

    function handleRemove(event: CustomEvent<RemoveEventDetail>) {
        const { itemIndex } = event.detail;
        items = removeItem(items, itemIndex);
    }
</script>

<SortableList on:sort={handleSort} on:remove={handleRemove}>
    {#each items as item, index (item.id)}
        <SortableItem id={item.id} {index}>
            <div class="ssl-item__content">
                {item.text}
            </div>
            <Remove>
                <IconRemove />
            </Remove>
        </SortableItem>
    {/each}
</SortableList>

Types

Example:

<script lang="ts">
    import type { RemoveEventDetail, SortEventDetail, SortableItemData } from '$lib/types/index.js';

    let items: SortableItemData[] = [
        {
            id: 'list-item-1',
            text: 'List item 1',
            isDisabled: false,
        },
        {
            id: 'list-item-2',
            text: 'List item 2',
            isDisabled: true,
        },
        {
            id: 'list-item-3',
            text: 'List item 3',
            isDisabled: true,
        },
        {
            id: 'list-item-4',
            text: 'List item 4',
            isDisabled: false,
        },
        {
            id: 'list-item-5',
            text: 'List item 5',
            isDisabled: false,
        },
    ];

    function handleSort(event: CustomEvent<SortEventDetail>) {
        const { prevItemIndex, nextItemIndex } = event.detail;
        items = sortItems(items, prevItemIndex, nextItemIndex);
    }

    function handleRemove(event: CustomEvent<RemoveEventDetail>) {
        const { itemIndex } = event.detail;
        items = removeItem(items, itemIndex);
    }
</script>

Styles

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

import 'svelte-sortable-list/styles.css';

Selectors

[!IMPORTANT] To customize the appearance of the list items and not cause any conflicts or interferences with the core styles and transitions, the usage of the .ssl-item selector must be avoided, pointing instead to .ssl-item__inner, which is the direct child of the aforementioned selector.

This is a list of the selectors you can use to style the list and the list items to your heart’s desire:

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 :)