Vue-arrange: Arrangeable lists for Vue3

Component library to drag and drop items across lists in Vue3. Try out here:

Comparable to, and inspired by, sortablejs, but unrelated.

Features:

• Rearranging a component list. Dragging/dropping items from one list to another.
• Fully customizable dragging element.
• Supports using a handle.
• Drop zones, e.g. for trash bin.
• Utility-class friendly
• Completely built in Typescript. Supports generic items. (Javascript users can live happily omitting all the type references below (the things between <>), but it is still useful to know what is being returned by events etc.)

Usage

To install

npm add vue-arrange

To run the example app

• clone the package
• npm i; npm run dev

Exports:

Component ArrangeableList

Props:

See ArrangeableProps below

Slots:

• #before: template to display something before the list of items.
  • Props:
    • arrangedItems: the list of items as it is rendered now.
• #default: template for the listed items;
  • Props:
    • item: the list item
    • arrangedItems: the list of items as it is rendered now.
• #after: template to display something after the list of items.
  • Props:
    • arrangedItems: the list of items as it is rendered now.

Events emitted:

• liftItem: fired when an item is being picked up out of this list. Payload: MovingItem.
• dropItem: fired when an item from this is dropped somewhere. Payload: MovingItem.

Notes

• The consumer needs to take care that the list prop gets stored/updated upon dropItem event, otherwise it the list will reset to its original position on the next re-render phase. This is can be done using the dropItem event, which carries a MovingItem argument with all the required information.
• Can be customized using options (see below).
  • class options can take any list of (utility) classes like they would be normally passed to a component. Tailwind works perfectly for example. They are empty by default.
  • There is no default transition for the list, this needs to be provided by the consumer (if desired) with the listTransition option.
  • by default, items can only be moved within the same list.
    • By adding a group (see options below), items can be moved between different lists with the same group name.
    • By adding one or more targets (see options below), items can be made to move only to lists with name or group listed in targets.
• It can be used both by touch devices, mouse and any other type of pointer, as it uses PointerEvents. To be able to do this, it puts touch-action: 'none' css class on the entire document.

Example

See example folder for example using tailwindcss.

Composable useMovingItem<PayloadType>()

Exposes:

• movingItem, of type MovingItem<PayloadType>; the item currently being dragged around by the user from any list at all. If using typescript, it should use the same PayloadType as the list items of the ArrangeableList.
• isMoving(item: PayloadType) => boolean; test whether item is currently being dragged.

const { movingItem, isMoving } = useMovingItem<MyObjectType>();

Types

MovingItem<PayloadType>

Information about what is/was being dragged/dropped.

type MovingItem<PayloadType> = {
  payload: PayloadType; // The item object being moved. PayloadType is a generic object
  hoverElement?: Ref<HTMLElement>; // the element ref of the hovering item.
  fromIndex: number; // the 0-based list-index where it was picked up.
  origin: string | symbol; // the name of the list from which it was picked up.
  originList: PayloadType[]; // the arranged items-list from where the item came as it appears now.
  toIndex?: number; // the 0-based list-index where the item is hovering or being dropped.
  destination?: string | symbol; // the name of the list where it is hovering over or being dropped.
  destinationList?: PayloadType[]; // the arranged items-list where the item is hovering over or being dropped as it appears now.
  originItemBoundingBox?: DOMRect; // the bounding box of the original location of the picked item.
  targets: Array<string | symbol>; // the names/groups of the lists where this item can be dropped.
};

ArrangeableOptions

options to pass to the arrangeable list.

type ArrangeableOptions = {
  hoverClass?: string; // class or classes to place on the element that is being dragged by the user
  pickedItemClass?: string; // class or classes to place on the original of the element in the list that is being picked up. Typically: 'invisible' or something like this.
  unpickedItemClass?: string; // class or classes to place on the items that are _not_ being picked up
  listTransition?: TransitionProps; // Transition props for the list, dictating how moving, removing and adding items to the list looks. See: Vue TransitionGroup documentation.
  hoverTransition?: TransitionProps; // Transition props for the hovered element. See: Vue Transition docuemntation.
  handle?: boolean; // indicate if the elements should be only dragged using a handle. If so, any descendant elements with attribute: 'name="handle"' are used as a handle.
};

ArrangeableProps<PayloadType>

props object for arrangeable list

type ArrangeableProps<PayloadType> = {
  options?: ArrangeableOptions; // See above
  list: PayloadType[]; // items passed to the list. PayloadType is the generic object type used by ArrangeableList.
  name?: symbol | string; // unique name of the list. Defaults to an unnamed symbol. Advised is to use a named symbol.
  group?: string | symbol; // group of the list. Items can be arbitrarily moved across member lists of this group.
  targets?: string | symbol | Array<string | symbol>; // By supplying one or more targets, items from this list can only be moved to other groups/lists named in 'targets' (using the name/group).
};