Svelte Sortable List

A comprehensive package for creating accessible, sortable lists in Svelte applications.

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

• Multi-input support: Mouse, keyboard, and touch interactions.
• Accessibility-first: Screen reader support with customizable announcements.
• Flexible layouts: Vertical and horizontal orientations with varying item heights.
• Enhanced UX: Drag handles, auto-scrolling, and customizable transitions.
• Advanced options: Axis locking, boundary constraints, and remove-on-drop-outside functionality.
• Integration: Support for nested interactive elements and <dialog> components.
• Internationalization: RTL language support.
• Developer-friendly: TypeScript definitions, unopinionated styling, and zero 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

This package prioritizes accessibility with comprehensive keyboard navigation and screen reader support.

Keyboard navigation

Navigation and interaction steps:

1. Press Tab to focus the list.
2. Use Arrow Up, Arrow Left, Arrow Down, Arrow Right, Home, or End to focus the first item.
3. Navigate between items:
   • Arrow Up or Arrow Left: Move to previous item.
   • Arrow Down or Arrow Right: Move to next item.
   • Home: Jump to first item.
   • End: Jump to last item.
4. Press Space to start dragging the focused item.
5. While dragging:
   • Use arrow keys to move the item to different positions.
   • Home: Move to first position.
   • End: Move to last position.
   • Space: Drop the item at current position.
   • Escape: Cancel drag and return item to original position.

Screen reader announcements customization

Customize screen reader announcements using two main approaches:

1. Navigation instructions (aria-description attribute): 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."

2. Drag-and-drop announcements (announcements prop): Customize announcements for lift, drag, drop, and cancel operations.

Additional customization options:

• aria-label: Provide a name for the list
• aria-labelledby: Reference an element that names the list

Example: Spanish translations

The following example demonstrates how to translate announcements to Spanish (adapted from the “With custom announcements” demo):

<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

This package follows the Compound Component Pattern, inspired in the remarkable work of Hunter Johnston in Bits UI. This pattern allows you to access modular components that work together seamlessly, all stemming from a single source.

[!WARNING] While you can use a standard <button> element instead of <SortableList.ItemRemove> to trigger item removal, the provided component offers additional benefits. It automatically focuses the next item in the list when a user removes an item via keyboard, preventing focus from falling back to the <body> element.

<SortableList.Root> props

[!WARNING] Wrapping limitations: Currently, wrapping support is limited to horizontal lists with items of identical width and height. Other variations may produce unexpected results.

<SortableList.Root> events

[!NOTE] Events fire in the order listed 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

Utility functions to simplify common list operations:

Example:

<script lang="ts">
    import { SortableList, 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

Built-in transition functions for smooth animations:

{
  delay: number
  duration: number
  easing: function
  axis: 'x' | 'y'
  x: number
  y: number
  opacity: number
}

Example:

<script lang="ts">
    import { SortableList, 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

TypeScript definitions for type-safe development:

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

Importing default styles

To use the demo page styles in your project:

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

Selectors

Use these CSS selectors to customize the appearance of list components:

[!IMPORTANT] Styling best practices: To prevent conflicts with core styles and transitions, avoid applying transitions directly through the .ssl-item and .ssl-ghost selectors. Instead, create a content wrapper element (like .ssl-item-content) as a child of .ssl-item. The ghost element will automatically mirror the list item’s content and appearance.

[!TIP] Advanced selector combinations: Combine the available selectors to target specific states. For example, to style the content of an item that is being dragged outside the list when canRemoveOnDropOut is enabled:

.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

CSS custom properties for global styling control:

Motivation

While working on a SvelteKit project, I ran into the need of adding drag-and-drop capabilities to a couple of item lists, for which I decided to go with SortableJS (a very popular option). I implemented it through a Svelte Action providing 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 using the HTML Drag and Drop API), but also accessibility was nowhere to be seen, and seems there were 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 :)