Dnd

The Drag and Drop (dnd) component provides a comprehensive solution for implementing drag and drop functionality in your applications. Built on top of SortableJS, it offers a flexible and customizable way to create sortable lists and handle drag-and-drop interactions.

Example

Architecture

dnd-list
Slot: default
dnd-item
Slot: default
dnd-handle
Slot: default

Reference

  • List

    The dnd-list is the primary component of the Spark Drag and Drop Package, providing a wrapper around SortableJS for integration into toddle. By default, any element placed inside the default slot - be it a div, an li element, or a custom component - becomes sortable through drag and drop. It works immediately without any attribute modifications, yet it allows for extensive customization to suit various use cases, implementing nearly all options from SortableJS.

    • Attributes

      • animation
        number
        /
        default: 150

        Defines the animation speed when moving items during sorting, in milliseconds. Set to 0 to disable animation.

      • chosen-class
        string
        /
        default: sortable-chosen

        Specifies the CSS class added to an item when it is chosen for dragging.

      • delay
        number
        /
        default: 100

        Specifies the delay in milliseconds before dragging starts. This is particularly useful for enabling smooth scrolling on mobile devices.

      • delay-on-touch-only
        boolean
        /
        default: true

        When enabled, the delay will only be applied on touch devices.

      • direction
        enum
        /
        default: vertical

        Determines the flex direction of the list. Choose between vertical or horizontal orientation.

      • disabled
        boolean
        /
        default: false

        Disables all dragging actions for this list when true.

      • drag-class
        string
        /
        default: sortable-drag

        Specifies the CSS class applied to an item while it is being dragged.

      • easing
        string
        /
        default: ease

        Defines the easing function used for drag and drop animations.

      • empty-insert-threshold
        number
        /
        default: 20

        Defines the minimum distance in pixels from an empty list required for a dragged element to be inserted.

      • fallback-class
        string
        /
        default: sortable-fallback

        Specifies the CSS class applied to the cloned DOM Element when using force-fallback mode.

      • filter-class
        string
        /
        default: -

        Class on elements preventing drag initiation, like “no-drag”.

      • flex-wrap
        enum
        /
        default: nowrap

        Controls how the list items wrap within the container using CSS flex-wrap property.

      • force-fallback
        boolean
        /
        default: true

        When enabled, forces the use of the fallback drag and drop implementation instead of HTML5 native DnD.

      • gap
        string
        /
        default: 0rem

        Sets the spacing between list items using CSS gap property.

      • ghost-class
        string
        /
        default: sortable-ghost

        Class added to the ghost item, which is the placeholder shown in the list during a drag.

      • group
        string
        /
        default: random ID

        Defines a group identifier that allows dragging items between lists sharing the same group value.

      • handle-class
        boolean
        /
        default: false

        Specifies a class for drag handle. If true, an internal handle class is generated and provided automatically. Alternatively you can specify your own handle-class name.

      • height
        string
        /
        default: auto

        Sets the height of the list container.

      • id
        string
        /
        default: -

        Provides a unique identifier for the list component.

      • invert-swap
        boolean
        /
        default: false

        When enabled, uses an inverted swap zone calculation for determining item placement.

      • inverted-swap-threshold
        number
        /
        default: 1

        Defines the threshold percentage (between 0 and 1) for the inverted swap zone calculation.

      • prevent-on-filter
        boolean
        /
        default: true

        When enabled, prevents default event behavior when a filtered element is attempted to be dragged.

      • sort
        boolean
        /
        default: true

        Enables sorting within the list.

      • swap-threshold
        number
        /
        default: 1

        Defines the threshold percentage (between 0 and 1) for the swap zone calculation.

      • tag
        enum
        /
        default: div

        Specifies the HTML element tag to be used for the list container.

      • touch-start-threshold
        number
        /
        default: 4

        Defines the minimum pointer movement in pixels required to cancel delayed sorting on touch displays.

      • width
        string
        /
        default: 100%

        Sets the width of the list container.

    • Events

      • On add

        Triggered when an element is dropped into the list from another list.

      • On change

        Triggered when a dragged element changes position within the list.

      • On clone

        Triggered when an element is cloned during a drag operation.

      • On end

        Triggered when a drag operation is completed.

      • On filter

        Triggered when attempting to drag an element that has a filter class applied.

      • On move

        Triggered during the movement of an item within or between lists.

      • On remove

        Triggered when an element is removed from the list.

      • On sort

        Triggered for any modification to the list (add, update, or remove).

      • On start

        Triggered when a drag operation begins.

      • On update

        Triggered when the order of items within the list changes.

    • Classes

      • horizontal

        Applied to the list container when the direction attribute is set to horizontal.

  • Item

    The dnd-item component functions as a helper within the drag-and-drop ecosystem, seamlessly integrating with the dnd-list. It inherits the dnd-list component's configuration and state via context and further extends this functionality to its child elements. Essentially, the dnd-item serves as a wrapper for your actual list items, conveying two key pieces of information to its children: whether the current item is being dragged (isChosen) and whether it serves as a placeholder for the drop target (isGhost). Additionally, it offers control over the dragged item's opacity through attributes.

    • Attributes

      • drag-opacity
        number
        /
        default: 1

        Controls the opacity of the item while being dragged, with values ranging from 0 to 1.

      • height
        string
        /
        default: auto

        Sets the height of the draggable item.

      • width
        string
        /
        default: 100%

        Sets the width of the draggable item.

  • Handle

    The dnd-handle component provides a designated drag handle for items within a dnd-list. When used, dragging can only be initiated from this handle, providing more precise control over drag operations.

    • Attributes

      • height
        string
        /
        default: auto

        Sets the height of the drag handle.

      • width
        string
        /
        default: 100%

        Sets the width of the drag handle.

Context

  • dndListContext

    Provides access to the current configuration for classes within the list component.

  • dndItemContext

    Provides access to the current state of the item, including whether it is being dragged (isChosen) or serving as a placeholder (isGhost).

made for toddle