Draggable

We use the draggable component to allow the user to intuitively move, place, or sort elements within a user interface.

Example

Usage

Giving users visual feedback during the process is crucial, indicating that they can grab, move and drop an element. Drag-and-drop usage in highly intricate UIs can pose challenges for users, as it may add an additional layer of complexity to their interactions. There is a risk of unintentional movements or actions if users inadvertently drag elements without intending to do so. Therefore, we strive to employ drag-and-drop primarily in simple contexts.

In very complex UIs, we use modals to isolate the drag-and-drop interaction from the rest of the UI. This enables us to focus users' attention on the drag-and-drop functionality and provides a controlled environment to prevent accidental actions or unintended movements. An example of this approach is the reordering of table columns, where a modal allows users to manipulate column positions without interference from the surrounding UIs.

Anatomy

Key elements

Element list. A list of draggable elements whose order reflects the order in which they appear in the interface.
Draggable element. An element of a list that can be moved to another position by drag & drop.
Drag icon. The icon (fa-solid fa-grip-vertical) indicates to the user that this is an element that can be grabbed.
Remove icon. A drag element can include various icons for further processing, such as the icon (fa-solid fa-times) to remove the element from the list.

States

Drag

Drag. The element is set to the dragged (wui-draggable__item--dragged) state after clicking and holding it. This way it can be repositioned within the list. The state is indicated by a lower opacity and added dropshadow that creates a hover impression.

Drop

Drop. The dragged element can be repositioned by releasing the key over a corresponding drop zone. The dropzone is characterized by a colored border ($color-active) and background ($color-active-10).

WUI use cases

Rearrange table columns

The draggable component is a central element of the rearrange table columns modal. Users can customize the columns of a table by selecting or deselecting them and then arranging them according to their preferences using the drag-and-drop functionality. The table's columns (from left to right) correspond to the draggable list (from top to bottom) in the modal.

Checkbox. The user can add table columns by checking and unchecking the checkboxes. The selected items will be included in the draggable area, allowing users to reorder them using the provided drag-and-drop feature.
Icon. As an addition to the checkboxes, items can be removed with the icon. Please note that not every element has a and is removable from the list.
Apply button. The action of reordering can become quite complex. In the modal, users always have the option to cancel the process and undo (unintended) decisions. Users can proceed by clicking the apply button when they are satisfied with their input.

Description

<wui-draggable> is simple component that is used for list items drag-and-drop to change order of items.

<wui-draggable v-model="items" />

<script>
  export default {
    data() {
      return {
        items: [
          {
            id: 1,
            label: "Item A",
            order: 1,
            fixed: false,
            hint: "",
          },
          {
            id: 2,
            label: "Item B",
            order: 2,
            fixed: false,
            hint: "Some hint",
          },
          {
            id: 3,
            label: "Item C",
            order: 3,
            fixed: false,
            hint: "",
          },
          {
            id: 4,
            label: "Item D",
            order: 4,
            fixed: true,
            hint: "",
          },
          {
            id: 5,
            label: "Item E",
            order: 5,
            fixed: false,
            hint: "",
          },
          {
            id: 6,
            label: "Item F",
            order: 6,
            fixed: true,
            hint: "",
          },
        ],
      };
    },
  };
</script>

`v-model` binding

To display draggable list developers need to pass items list via v-model binding. It needs to be array of objects that have specific structure. id unique item id. label is used to display item label, hint is displayed next to label and is optional. order sets initial items order. fixed is used to set item as non-draggable and non-removable.

Custom list styles

Developers have an option to use override item content via default scoped slot.

<wui-draggable v-model="items">
  <template #default="{ item }">
    <div :draggable="!item.fixed">{ item.label }</div>
  </template>
</wui-draggable>

<script>
  export default {
    data() {
      return {
        items: [
          {
            id: 1,
            label: "Item A",
            order: 1,
            fixed: false,
            hint: "",
          },
          {
            id: 2,
            label: "Item B",
            order: 2,
            fixed: false,
            hint: "Some hint",
          },
          {
            id: 3,
            label: "Item C",
            order: 3,
            fixed: false,
            hint: "",
          },
          {
            id: 4,
            label: "Item D",
            order: 4,
            fixed: true,
            hint: "",
          },
          {
            id: 5,
            label: "Item E",
            order: 5,
            fixed: false,
            hint: "",
          },
          {
            id: 6,
            label: "Item F",
            order: 6,
            fixed: true,
            hint: "",
          },
        ],
      };
    },
  };
</script>

Component reference

Properties

Property	Type	Default	Description
`items` v-model	`Array`	`[]`	Array of draggable item objects
`hideDropzone`	`Boolean`	`false`	Used to hide dropzone element that is displayed when item is being dragged over another item

`v-model`

Property	Event
`items`	`update`

Slots

Name	Scope	Description
default	Yes, see below	Content to place in the Draggable

Default slot scope:

Prop	Type	Description
`item`	`Object`	Object containing list item data

Events

Event	Arguments	Description
`update`	`items` - Reordered items list	Fired when items order is updated (v-model event)
`dragstart`	`event` - `DragEvent` Native dragstart event `item` - Dragged item	Event that is fired when the user starts dragging an element
`dragover`	`event` - `DragEvent` Native dragover event `item` - Dragged item	Event that is fired when an element is being dragged over a valid drop target (every few hundred milliseconds)
`drop`	`event` - `DragEvent` Native drop event `item` - Dragged item `index` - Dragged item dropped on index position	Event that is fired when an element is dropped on a valid drop target. Cancelable. Call `event.preventDefault()` to cancel drop and subsequent `v-modal` update
`dragend`	`event` - `DragEvent` Native dragend event	Event that is fired when a drag operation is being ended (by releasing a mouse button or hitting the escape key)
`removed`	`event` - `Event` Native click event `item` - Removed item	Click event that is fired when remove item button is clicked. Cancelable. Call `event.preventDefault()` to cancel drop and subsequent `v-modal` update

Importing individual components

You can import individual components into your project via the following named exports:

Component	Named Export
`<wui-draggable>`	`WuiDraggable`

Example

import { WuiDraggable } from "@wui/wui-vue/lib";
Vue.component("wui-draggable", WuiDraggable);

Importing as a Vue.js plugin

This plugin includes all of the above listed individual components. Plugins also include any component aliases.

Named Export	Import Path
`DraggablePlugin`	`@wui/wui-vue/lib`